功能 ​

CSS ​

导入 .css 文件将会把内容插入到 <style> 标签中，同时也带有 HMR 支持。

@import 内联和变基 ​

Vite 通过 postcss-import 预配置支持了 CSS @import 内联，Vite 的路径别名也遵从 CSS @import 。换句话说，所有 CSS url() 引用，即使导入的文件在不同的目录中，也总是自动变基，以确保正确性。

Sass 和 Less 文件也支持 @import 别名和 URL 变基（具体请参阅 CSS 预处理器 ）。

PostCSS ​

如果项目包含有效的 PostCSS 配置 (任何受 postcss-load-config 支持的格式，例如 postcss.config.js )，它将会自动应用于所有已导入的 CSS。

请注意，CSS 最小化压缩将在 PostCSS 之后运行，并会使用 build.cssTarget 选项。

CSS Modules ​

任何以 .module.css 为后缀名的 CSS 文件都被认为是一个 CSS modules 文件 。导入这样的文件会返回一个相应的模块对象：

.red {
  color: red;
}

import 
classes
 from './example.module.css'
document
.
getElementById
('foo'




    
).
className
 = 
classes
.
red

CSS modules 行为可以通过 css.modules 选项 进行配置。

如果 css.modules.localsConvention 设置开启了 camelCase 格式变量名转换（例如 localsConvention: 'camelCaseOnly' ），你还可以使用按名导入。

// .apply-color -> applyColor
import { 
applyColor
 } from './example.module.css'
document
.
getElementById
('foo').
className
 = 
applyColor

CSS 预处理器 ​

由于 Vite 的目标仅为现代浏览器，因此建议使用原生 CSS 变量和实现 CSSWG 草案的 PostCSS 插件（例如 postcss-nesting ）来编写简单的、符合未来标准的 CSS。

话虽如此，但 Vite 也同时提供了对 .scss , .sass , .less , .styl 和 .stylus 文件的内置支持。没有必要为它们安装特定的 Vite 插件，但必须安装相应的预处理器依赖：

# .scss 和 .sass
npm add -D sass-embedded # 或 sass
# .less
npm add -D less
# .styl 和 .stylus
npm add -D stylus

如果使用的是单文件组件，可以通过 <style lang="sass"> （或其他预处理器）自动开启。

Vite 为 Sass 和 Less 改进了 @import 解析，以保证 Vite 别名也能被使用。另外， url() 中的相对路径引用的，与根文件不同目录中的 Sass/Less 文件会自动变基以保证正确性。

由于 Stylus API 限制， @import 别名和 URL 变基不支持 Stylus。

你还可以通过在文件扩展名前加上 .module 来结合使用 CSS modules 和预处理器，例如 style.module.scss 。

禁用 CSS 注入页面 ​

自动注入 CSS 内容的行为可以通过 ?inline 参数来关闭。在关闭时，被处理过的 CSS 字符串将会作为该模块的默认导出，但样式并没有被注入到页面中。

import './foo.css' // 样式将会注入页面
import 
otherStyles
 from './bar.css?inline' // 样式不会注入页面

Lightning CSS ​

从 Vite 4.4 开始，已经实验性地支持 Lightning CSS 。可以通过在配置文件中添加 css.transformer: 'lightningcss' 并安装可选的 lightningcss 依赖项来选择使用它：

npm add -D lightningcss

如果启用，CSS 文件将由 Lightning CSS 处理，而不是 PostCSS。可以将 Lightning CSS 的选项传递给 css.lightningcss 选项来配置。

要配置 CSS Modules，需要使用 css.lightningcss.cssModules 而不是 css.modules （后者是用于配置 PostCSS 处理 CSS Modules 的方式）。

默认情况下，Vite 使用 esbuild 来压缩 CSS。通过 build.cssMinify: 'lightningcss' 进行配置，也可以将 Lightning CSS 用作 CSS 最小化压缩。

静态资源处理 ​

导入一个静态资源会返回解析后的 URL：

import 
imgUrl
 from './img.png'
document
.
getElementById
('hero-img').src = 
imgUrl

添加一些特殊的查询参数可以更改资源被引入的方式：

// 显式加载资源为一个 URL
import 
assetAsURL
 from './asset.js?url'

// 以字符串形式加载资源
import 
assetAsString
 from './shader.glsl?raw'

// 加载为 Web Worker
import 
Worker
 from './worker.js?worker'

// 在构建时 Web Worker 内联为 base64 字符串




    

import 
InlineWorker
 from './worker.js?worker&inline'

更多细节请见 静态资源处理 。

JSON ​

JSON 可以被直接导入 —— 同样支持具名导入：

// 导入整个对象
import 
json
 from './example.json'
// 对一个根字段使用具名导入 —— 有效帮助 treeshaking！
import { 
field
 } from './example.json'

Glob 导入 ​

Vite 支持使用特殊的 import.meta.glob 函数从文件系统导入多个模块：

const 
modules
 = import.meta.
glob
('./dir/*.js')

以上将会被转译为下面的样子：

// vite 生成的代码
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
  './dir/bar.js': () => import('./dir/bar.js'),
}

你可以遍历 modules 对象的 key 值来访问相应的模块：

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod)
}

匹配到的文件默认是懒加载的，通过动态导入实现，并会在构建时分离为独立的 chunk。如果你倾向于直接引入所有的模块（例如依赖于这些模块中的副作用首先被应用），你可以传入 { eager: true } 作为第二个参数：

const 
modules
 = import.meta.
glob





    
('./dir/*.js', { 
eager
: true })

以上会被转译为下面的样子：

// vite 生成的代码
import * as __glob__0_0 from './dir/foo.js'
import * as __glob__0_1 from './dir/bar.js'
const modules = {
  './dir/foo.js': __glob__0_0,
  './dir/bar.js': __glob__0_1,
}

多个匹配模式 ​

第一个参数可以是一个 glob 数组，例如：

const 
modules
 = import.meta.
glob
(['./dir/*.js', './another/*.js'])

反面匹配模式 ​

同样也支持反面 glob 匹配模式（以 ! 作为前缀）。若要忽略结果中的一些文件，你可以添加“排除匹配模式”作为第一个参数：

const 
modules
 = import.meta.
glob
(['./dir/*.js', '!**/bar.js'])

// vite 生成的代码
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
}

具名导入 ​

也可能你只想要导入模块中的部分内容，那么可以利用 import 选项。

const 
modules
 = import.meta.
glob





    
('./dir/*.js', { 
import
: 'setup' })

// vite 生成的代码
const modules = {
  './dir/foo.js': () => import('./dir/foo.js').then((m) => m.setup),
  './dir/bar.js': () => import('./dir/bar.js').then((m) => m.setup),
}

当与 eager 一同存在时，甚至可以对这些模块进行 tree-shaking。

const 
modules
 = import.meta.
glob
('./dir/*.js', {
  
import
: 'setup',
  
eager
: true,
})

// vite 生成的代码
import { setup as __glob__0_0 } from './dir/foo.js'
import { setup as __glob__0_1 } from './dir/bar.js'
const modules = {
  './dir/foo.js': __glob__0_0,
  './dir/bar.js': __glob__0_1,
}

设置 import 为 default 可以加载默认导出。

const 
modules
 = import.meta.
glob
('./dir/*.js', {
  
import
: 'default'




    
,
  
eager
: true,
})

// vite 生成的代码
import __glob__0_0 from './dir/foo.js'
import __glob__0_1 from './dir/bar.js'
const modules = {
  './dir/foo.js': __glob__0_0,
  './dir/bar.js': __glob__0_1,
}

自定义查询 ​

你也可以使用 query 选项来提供对导入的自定义查询，比如，可以将资源 作为字符串引入 或者 作为 URL 引入 ：

const 
moduleStrings
 = import.meta.
glob
('./dir/*.svg', {
  
query
: '?raw',
  
import
: 'default',
const 
moduleUrls
 = import.meta.
glob
('./dir/*.svg', {
  
query
: '?url',
  
import
: 'default',
})

// vite 生成的代码
const moduleStrings = {
  './dir/foo.svg': () => import('./dir/foo.js?raw').then((m) => m['default']),
  './dir/bar.svg': () => import(




    
'./dir/bar.js?raw').then((m) => m['default']),
const moduleUrls = {
  './dir/foo.svg': () => import('./dir/foo.js?url').then((m) => m['default']),
  './dir/bar.svg': () => import('./dir/bar.js?url').then((m) => m['default']),
}

你还可以为其他插件提供定制化的查询参数：

const 
modules
 = import.meta.
glob
('./dir/*.js', {
  
query
: { 
foo
: 'bar', 
bar
: true },
})

Glob 导入注意事项 ​

请注意：

• 这只是一个 Vite 独有的功能而不是一个 Web 或 ES 标准
• 该 Glob 模式会被当成导入标识符：必须是相对路径（以 ./ 开头）或绝对路径（以 / 开头，相对于项目根目录解析）或一个别名路径（请看 resolve.alias 选项 )。
• Glob 匹配是使用 tinyglobby 来实现的 —— 阅读它的文档来查阅 支持的 Glob 模式 。
• 你还需注意，所有 import.meta.glob 的参数都必须以字面量传入。你 不 可以在其中使用变量或表达式。

动态导入 ​

和 glob 导入 类似，Vite 也支持带变量的动态导入。

const module = await import(`./dir/${file}.js`)

注意变量仅代表一层深的文件名。如果 file 是 foo/bar ，导入将会失败。对于更进阶的使用详情，你可以使用 glob 导入 功能。

WebAssembly ​

预编译的 .wasm 文件可以通过 ?init 来导入。 默认导出一个初始化函数，返回值为所导出 WebAssembly.Instance 实例对象的 Promise：

import 
init
 from './example.wasm?init'
init
().
then
((
instance
) => {
  
instance
.
exports
.
test
()
})

init 函数还可以将传递给 WebAssembly.instantiate 的导入对象作为其第二个参数：

init
({
  
imports
: {
    
someFunc
: () => {
      /* ... */
}).
then




    
(() => {
  /* ... */
})

在生产构建当中，体积小于 assetInlineLimit 的 .wasm 文件将会被内联为 base64 字符串。否则，它们将被视为 静态资源 ，并按需获取。

访问 WebAssembly 模块 ​

如果需要访问 Module 对象，例如将它多次实例化，可以使用 显式 URL 引入 来解析资源，然后执行实例化：

import 
wasmUrl
 from 'foo.wasm?url'
const 
main
 = async () => {
  const 
responsePromise
 = 
fetch
(
wasmUrl
)
  const { 
module
, 
instance
 } =
    await WebAssembly.
instantiateStreaming
(
responsePromise
)
  /* ... */
main
()




    

在 Node.js 中获取模块 ​

在 SSR 中，作为 ?init 导入的 fetch() 可能会失败，导致 TypeError: Invalid URL 报错。 请参见问题 在 SSR 中支持 wasm 。

以下是一种替代方案，假设项目根目录在当前目录：

import 
wasmUrl
 from 'foo.wasm?url'
import { 
readFile
 } from 'node:fs/promises'
const 
main
 = async () => {
  const 
resolvedUrl
 = (await import('./test/boot.test.wasm?url')).
default

  const 
buffer
 = await 
readFile
('.' + 
resolvedUrl
)
  const { 
instance
 } = await WebAssembly.
instantiate
(
buffer
, {
    /* ... */
  /* ... */
main
()

Web Workers ​

通过构造器导入 ​

一个 Web Worker 可以使用 new Worker() 和 new SharedWorker() 导入。与 worker 后缀相比，这种语法更接近于标准，是创建 worker 的 推荐 方式。

const worker = new Worker(new URL('./worker.js', import.meta.url))

worker 构造函数会接受可以用来创建 “模块” worker 的选项：

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
})

只有在 new Worker() 声明中直接使用 new URL() 构造函数时，work 线程的检测才会生效。此外，所有选项参数必须是静态值（即字符串字面量）。

带有查询后缀的导入 ​

你可以在导入请求上添加 ?worker 或 ?sharedworker 查询参数来直接导入一个 web worker 脚本。默认导出会是一个自定义 worker 的构造函数：

import 
MyWorker
 from './worker?worker'
const 
worker
 = new 
MyWorker




    
()

这个 worker 脚本也可以使用 ESM import 语句而不是 importScripts() 。 注意 ：在开发时，这依赖于 浏览器原生支持 ，但是在生产构建中，它会被编译掉。

默认情况下，worker 脚本将在生产构建中编译成单独的 chunk。如果你想将 worker 内联为 base64 字符串，请添加 inline 查询参数：

import 
MyWorker
 from './worker?worker&inline'

如果你想要以一个 URL 的形式读取该 worker，请添加 url 这个 query：

import 
MyWorker
 from './worker?worker&url'

关于如何配置打包全部 worker，可以查看 Worker 选项 了解更多相关细节。

内容安全策略（CSP） ​

由于 Vite 的内部机制，为了部署 CSP 必须设置某些指令或配置。

'nonce-{RANDOM}' ​

当设置了 html.cspNonce 时，Vite 会为任何 <script> 和 <style> 标签，以及样式表和模块预加载的 <link> 标签添加一个 nonce 属性。此外，当设置了这个选项时，Vite 会注入一个 meta 标签 ( <meta property="csp-nonce" nonce="PLACEHOLDER" /> )。

带有 property="csp-nonce" 的 meta 标签的 nonce 值将在开发和构建后的必要时刻被 Vite 使用。

data: ​

默认情况下，Vite 在构建过程中会将小型资源内联为 data URI。允许 data: 用于相关指令（例如 img-src ， font-src ），或者，通过设置 build.assetsInlineLimit: 0 来禁用它是必要的。

构建优化 ​

下面所罗列的功能会自动应用为构建过程的一部分，除非你想禁用它们，否则没有必要显式配置。

CSS 代码分割 ​

Vite 会自动地将一个异步 chunk 模块中使用到的 CSS 代码抽取出来并为其生成一个单独的文件。这个 CSS 文件将在该异步 chunk 加载完成时自动通过一个 <link> 标签载入，该异步 chunk 会保证只在 CSS 加载完毕后再执行，避免发生 FOUC 。

如果你更倾向于将所有的 CSS 抽取到一个文件中，你可以通过设置 build.cssCodeSplit 为 false 来禁用 CSS 代码分割。

预加载指令生成 ​

Vite 会为入口 chunk 和它们在打包出的 HTML 中的直接引入自动生成 <link rel="modulepreload"> 指令。

异步 Chunk 加载优化 ​

在实际项目中，Rollup 通常会生成 “共用” chunk —— 被两个或以上的其他 chunk 共享的 chunk。与动态导入相结合，会很容易出现下面这种场景：