您正在浏览 Nuxt 2 文档。前往 Nuxt 3 文档, 或了解更多关于 Nuxt 2 长期支持

资源目录

assets 目录包含未编译的资源,如 Stylus 或 Sass 文件、图片或字体。


图片

vue 模板中需要链接到 assets 目录时,在 assets 前加斜杠,写成 ~/assets/your_image.png

<template>
  <img src="~/assets/your_image.png" />
</template>

css 文件中需要链接到 assets 目录时,不加斜杠,写成 ~assets/your_image.png

background: url('~assets/banner.svg');

使用动态图片时,需要使用 require。

<img :src="require(`~/assets/img/${image}.jpg`)" />

样式

Nuxt 允许定义全局(所有页面)应用的 CSS 文件、模块和库。在 nuxt.config 中使用 CSS 属性可以轻松添加样式。

nuxt.config.js
export default {
  css: [
    // 直接加载 Node.js 模块(此处为 Sass 文件)
    'bulma',
    // 项目中的 CSS 文件
    '~/assets/css/main.css',
    // 项目中的 SCSS 文件
    '~/assets/css/main.scss'
  ]
}

Sass

如果想使用 sass,请确认已安装 sasssass-loader 插件。

Yarn
yarn add --dev sass sass-loader@10
NPM
npm install --save-dev sass sass-loader@10

Nuxt 会自动从扩展名推断文件类型,并使用适当的预处理器 loader。如果需要,仍需自行安装所需的 loader。

字体

将本地字体添加到 assets 文件夹后即可使用,然后通过 CSS 中的 @font-face 访问。

-| assets
----| fonts
------| DMSans-Regular.ttf
------| DMSans-Bold.ttf
assets/main.css
@font-face {
  font-family: 'DM Sans';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('~assets/fonts/DMSans-Regular.ttf') format('truetype');
}

@font-face {
  font-family: 'DM Sans';
  font-style: normal;
  font-weight: 700;
  font-display: swap;
  src: url('~assets/fonts/DMSans-Bold.ttf') format('truetype');
}
CSS 文件不会自动加载,需要使用 CSS 配置属性 添加它们。

Webpack 资源

默认情况下,Nuxt 使用 webpack 的 vue-loader、file-loader 和 url-loader 来提供资源。也可以使用 static 目录存放不应通过 webpack 处理的资源。

Webpack

vue-loader 使用 css-loader 和 Vue Template Compiler 自动处理样式和模板文件。在此编译过程中,所有资源 URL(如 <img src="...">background: url(...) 和 CSS @import)都会被解析为模块依赖项。

例如,有以下文件结构:

-| assets/
----| image.png
-| pages/
----| index.vue

在 CSS 中写 url('~assets/image.png') 时,会被转换为 require('~/assets/image.png')

~/ 别名在 CSS 文件中可能无法正确解析。CSS url 引用中必须使用 ~assets不带斜杠),例如:background: url("~assets/banner.svg")

pages/index.vue 中引用图片时:

pages/index.vue
<template>
  <img src="~/assets/image.png" />
</template>

会被编译为:

createElement('img', { attrs: { src: require('~/assets/image.png') } })

由于 .png 不是 JavaScript 文件,Nuxt 会配置 webpack 使用 file-loader url-loader 来处理它们。

这些 loader 的优点:

file-loader 可以指定资源文件的复制和放置位置,以及如何使用版本哈希命名文件以改善缓存。在生产环境中,默认可以享受长期缓存的好处。

url-loader 可以在文件小于指定阈值时,有条件地将文件内联为 Base64 数据 URL,从而减少小文件的 HTTP 请求数。如果文件大于阈值,会自动回退到 file-loader。

这两个 loader 的默认配置如下:

// https://github.com/nuxt/nuxt/blob/2.x-dev/packages/webpack/src/config/base.js#L382-L411
{
  test: /\.(png|jpe?g|gif|svg|webp|avif)$/i,
  use: [{
    loader: 'url-loader',
    options: {
      esModule: false,
      limit: 1000, // 1kB
      name: 'img/[name].[contenthash:7].[ext]'
    }
  }]
},
{
  test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/i,
  use: [{
    loader: 'url-loader',
    options: {
       esModule: false,
       limit: 1000, // 1kB
       name: 'fonts/[name].[contenthash:7].[ext]'
    }
  }]
},
{
  test: /\.(webm|mp4|ogv)$/i,
  use: [{
    loader: 'file-loader',
    options: {
      esModule: false,
      name: 'videos/[name].[contenthash:7].[ext]'
    }
  }]
}

也就是说,所有小于 1 KB 的文件都会被内联为 Base64 数据 URL,否则图片和字体会被复制到对应文件夹(在 .nuxt 目录下),并以包含版本哈希的名称命名以改善缓存。

使用 nuxt 命令启动应用程序时,pages/index.vue 中的模板:

pages/index.vue
<template>
  <img src="~/assets/your_image.png" />
</template>

会生成为:

<img src="/_nuxt/img/your_image.0c61159.png" />

如果想更改 loader 配置,请使用 build.extend

别名

默认情况下,源目录(srcDir)和根目录(rootDir)指向同一目录。源目录可以使用 ~ 别名。可以用 ~/assets/your_image.png 代替 ../assets/your_image.png 这样的相对路径。

两者结果相同:

components/Avatar.vue
<template>
  <div>
    <img src="../assets/your_image.png" />
    <img src="~/assets/your_image.png" />
  </div>
</template>

建议使用 ~ 作为别名。@ 仍然受支持,但在 CSS background image 等所有情况下可能无法正常工作。

根目录可以使用 ~~@@ 别名。

提示:在西班牙语键盘上,Mac OS 可以通过(Option + ñ),Windows 可以通过(Alt gr + 4)输入 ~
Edit this page on GitHub Updated at Tue, Apr 14, 2026