配置文件
当以命令行方式运行 vite
时,Vite 会自动解析项目根目录下名为 vite.config.js
的配置文件(也支持其他 JS 和 TS 扩展名)。
最基础的配置文件是这样的:
js
// vite.config.js
export default {
// 配置选项
}
注意:即使项目没有在 package.json
中开启 type: "module"
,Vite 也支持在配置文件中使用 ESM 语法。这种情况下,配置文件会在被加载前自动进行预处理。
你可以显式地通过 --config
命令行选项指定一个配置文件(相对于 cwd
路径进行解析)
bash
vite --config my-config.js
情景配置
如果配置文件需要基于(dev
/serve
或 build
)命令或者不同的 模式 来决定选项,亦或者是一个 SSR 构建(isSsrBuild
)、一个正在预览的构建产物(isPreview
),则可以选择导出这样一个函数:
export default defineConfig(async ({ command, mode }) => {
const data = await asyncFunction()
return {
// vite 配置
}
})
需要注意的是,在 Vite 的 API 中,在开发环境下 command
的值为 serve
(在 CLI 中, vite dev
和 vite serve
是 vite 的别名),而在生产环境下为 build
(vite build)。
isSsrBuild
和 isPreview
是额外的可选标志,用于区分 build
和 serve
命令的类型。一些加载 Vite 配置的工具可能不支持这些标志,而会传递 undefined
。因此,建议使用 true
和 false
的显式比较。
异步配置
如果配置需要调用一个异步函数,也可以转而导出一个异步函数。这个异步函数也可以通过 defineConfig
传递,以便获得更好的智能提示:
js
import { defineConfig, loadEnv } from 'vite'
export default defineConfig(({ command, mode }) => {
// 根据当前工作目录中的 `mode` 加载 .env 文件
// 设置第三个参数为 '' 来加载所有环境变量,而不管是否有 `VITE_` 前缀。
const env = loadEnv(mode, process.cwd(), '')
return {
// vite 配置
define: {
__APP_ENV__: JSON.stringify(env.APP_ENV),
},
}
})
在配置中使用环境变量
环境变量通常可以从 process.env
获得。
注意 Vite 默认是不加载 .env
文件的,因为这些文件需要在执行完 Vite 配置后才能确定加载哪一个,举个例子,root
和 envDir
选项会影响加载行为。不过当你的确需要时,你可以使用 Vite 导出的 loadEnv
函数来加载指定的 .env
文件。
import { defineConfig, loadEnv } from 'vite'
export default defineConfig(({ command, mode }) => {
// 根据当前工作目录中的 `mode` 加载 .env 文件
// 设置第三个参数为 '' 来加载所有环境变量,而不管是否有 `VITE_` 前缀。
const env = loadEnv(mode, process.cwd(), '')
return {
// vite 配置
define: {
__APP_ENV__: JSON.stringify(env.APP_ENV),
},
}
})
项目根目录
你可能已经注意到,在一个 Vite 项目中,index.html
在项目最外层而不是在 public
文件夹内。这是有意而为之的:在开发期间 Vite 是一个服务器,而 index.html
是该 Vite 项目的入口文件。
Vite 将 index.html
视为源码和模块图的一部分。
Vite 解析 <script type="module" src="...">
,这个标签指向你的 JavaScript 源码。甚至内联引入 JavaScript 的 <script type="module">
和引用 CSS 的 <link href>
也能利用 Vite 特有的功能被解析。另外,index.html
中的 URL 将被自动转换,因此不再需要 %PUBLIC_URL%
占位符了。
与静态 HTTP 服务器类似,Vite 也有 “根目录” 的概念,即服务文件的位置,在接下来的文档中你将看到它会以 <root>
代称。源码中的绝对 URL 路径将以项目的 “根” 作为基础来解析,因此你可以像在普通的静态文件服务器上一样编写代码(并且功能更强大!)。Vite 还能够处理依赖关系,解析处于根目录外的文件位置,这使得它即使在基于 monorepo 的方案中也十分有用。
Vite 也支持多个 .html
作入口点多页面应用模式。
指定替代根目录
vite
以当前工作目录作为根目录启动开发服务器。你也可以通过 vite serve some/sub/dir
来指定一个替代的根目录。注意 Vite 同时会解析项目根目录下的配置文件vite.config.js,因此如果根目录被改变了,你需要将配置文件移动到新的根目录下。
多页面应用模式
假设你有下面这样的项目文件结构
├── package.json
├── vite.config.js
├── index.html
├── main.js
└── nested
├── index.html
└── nested.js
在开发过程中,简单地导航或链接到 /nested/
- 将会按预期工作,与正常的静态文件服务器表现一致。
在构建过程中,你只需指定多个 .html
文件作为入口点即可:
js
// vite.config.js
import { resolve } from 'path'
import { defineConfig } from 'vite'
export default defineConfig({
build: {
rollupOptions: {
input: {
main: resolve(__dirname, 'index.html'),
nested: resolve(__dirname, 'nested/index.html'),
},
},
},
})
如果你指定了另一个根目录,请记住,在解析输入路径时,__dirname
的值将仍然是 vite.config.js 文件所在的目录。因此,你需要把对应入口文件的 root
的路径添加到 resolve
的参数中。
请注意,在 HTML 文件中,Vite 忽略了 rollupOptions.input
对象中给定的入口名称,而是在生成 dist 文件夹中的 HTML 资源文件时,使用了文件已解析的路径 ID。这确保了与开发服务器的工作方式保持一致的结构。