release v3.2.0

.vitepress/config.ts

@@ -21,7 +21,16 @@ export default defineConfig({
     ['meta', { property: 'og:description', content: ogDescription }],
     ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
     ['meta', { name: 'twitter:site', content: '@vite_js' }],
-    ['meta', { name: 'theme-color', content: '#646cff' }]
+    ['meta', { name: 'theme-color', content: '#646cff' }],
+    [
+      'script',
+      {
+        src: 'https://cdn.usefathom.com/script.js',
+        'data-site': 'CBDFBSLI',
+        'data-spa': 'auto',
+        defer: ''
+      }
+    ]
   ],
 
   vue: {

config/build-options.md

@@ -10,28 +10,62 @@
 
 另一个特殊值是 “esnext” —— 即假设有原生动态导入支持，并且将会转译得尽可能小：
 
-- 如果 [`build.minify`](#build-minify) 选项为 `'terser'`， `'esnext'` 将会强制降级为 `'es2019'`。
+- 如果 [`build.minify`](#build-minify) 选项为 `'terser'`，`'esnext'` 将会强制降级为 `'es2019'`。
 - 其他情况下将完全不会执行转译。
 
 转换过程将会由 esbuild 执行，并且此值应该是一个合法的 [esbuild 目标选项](https://esbuild.github.io/api/#target)。自定义目标也可以是一个 ES 版本（例如：`es2015`）、一个浏览器版本（例如：`chrome58`）或是多个目标组成的一个数组。
 
 注意：如果代码包含不能被 `esbuild` 安全地编译的特性，那么构建将会失败。查看 [esbuild 文档](https://esbuild.github.io/content-types/#javascript) 获取更多细节。
 
-## build.polyfillModulePreload {#build-polyfillmodulepreload}
+## build.modulePreload {#build-modulepreload}
 
-- **类型：** `boolean`
+- **类型：** `boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }`
 - **默认值：** `true`
 
-用于决定是否自动注入 [module preload 的 polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill).
-
-如果设置为 `true`，此 polyfill 会被自动注入到每个 `index.html` 入口的 proxy 模块中。如果是通过 `build.rollupOptions.input` 将构建配置为使用非 html 的自定义入口，那么则需要在你自定义入口中手动引入 polyfill：
+默认情况下，一个 [模块预加载 polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill) 会被自动注入。该 polyfill 会自动注入到每个 `index.html` 入口的的代理模块中。如果构建通过 `build.rollupOptions.input` 被配置为了使用非 HTML 入口的形式，那么必须要在你的自定义入口中手动引入该 polyfill：
 
 ```js
 import 'vite/modulepreload-polyfill'
 ```
 
 注意：此 polyfill **不适用于** [Library 模式](/guide/build#library-mode)。如果你需要支持不支持动态引入的浏览器，你应该避免在你的库中使用此选项。
 
+此 polyfill 可以通过 `{ polyfill: false }` 来禁用。
+
+每个动态导入要预加载的块列表将由 Vite 计算。默认情况下，在载入这些依赖时，会使用一个包含 `base` 的绝对路径。如果 `base` 是相对路径（`''` 或者 './'），解析时则会使用 `import.meta.url`，以避免出现依赖于最终部署基路径的绝对路径。
+
+目前有一个实验性功能支持使用 `resolveDependencies` 函数对依赖项列表及其路径进行细粒度控制。它期望接收一个 `ResolveModulePreloadDependenciesFn` 类型的函数:
+
+```ts
+type ResolveModulePreloadDependenciesFn = (
+  url: string,
+  deps: string[],
+  context: {
+    importer: string
+  }
+) => (string | { runtime?: string })[]
+```
+
+`resolveDependencies` 函数将为每个动态导入调用，同时带着一个它所依赖的 chunk 列表。并且它还会为每个在入口 HTML 文件中导入的 chunk 调用。 可以返回一个新的依赖关系数组，可能被过滤后变少了，也可能有更多依赖注入进来了，同时它们的路径也被修改过。`deps` 路径是相对于 `build.outDir` 的。若在注入该模块到 HTML head 时使用 `new URL(dep, import.meta.url)` 获取绝对路径，则对于 `hostType === 'js'`，允许返回一个相对于 `hostId` 的路径。
+
+```js
+modulePreload: {
+  resolveDependencies: (filename, deps, { hostId, hostType }) => {
+    return deps.filter(condition)
+  }
+}
+```
+
+解析得到的依赖路径可以再在之后使用 [`experimental.renderBuiltUrl`](../guide/build.md#advanced-base-options) 更改。
+
+## build.polyfillModulePreload {#build-polyfillmodulepreload}
+
+- **类型：** `boolean`
+- **默认：** `true`
+- **已废弃** 请使用 `build.modulePreload.polyfill` 替代
+
+是否自动注入一个 [模块预加载 polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill)。
+
 ## build.outDir {#build-outdir}
 
 - **类型：** `string`
@@ -111,10 +145,10 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含它们所
 
 ## build.lib {#build-lib}
 
-- **类型：** `{ entry: string, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat) => string) }`
+- **类型：** `{ entry: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string) }`
 - **相关内容：** [库模式](/guide/build#library-mode)
 
-构建为库。`entry` 是必须的因为库不能使用 HTML 作为入口。`name` 则是暴露的全局变量，在 `formats` 包含 `'umd'` 或 `'iife'` 时是必须的。默认 `formats` 是 `['es', 'umd']` 。`fileName` 是输出的包文件名，默认 `fileName` 是 `package.json` 的 `name` 选项，同时，它还可以被定义为参数为 `format` 的函数。
+构建为库。`entry` 是必需的，因为库不能使用 HTML 作为入口。`name` 则是暴露的全局变量，并且在 `formats` 包含 `'umd'` 或 `'iife'` 时是必需的。默认 `formats` 是 `['es', 'umd']`，如果使用了多个配置入口，则是 `['es', 'cjs']`。`fileName` 是输出的包文件名，默认 `fileName` 是 `package.json` 的 `name` 选项，同时，它还可以被定义为参数为 `format` 和 `entryAlias` 的函数。
 
 ## build.manifest {#build-manifest}
 
@@ -175,6 +209,14 @@ npm add -D terser
 
 默认情况下，若 `outDir` 在 `root` 目录下，则 Vite 会在构建时清空该目录。若 `outDir` 在根目录之外则会抛出一个警告避免意外删除掉重要的文件。可以设置该选项来关闭这个警告。该功能也可以通过命令行参数 `--emptyOutDir` 来使用。
 
+## build.copyPublicDir {#build-copypublicdir}
+
+- **实验性特性**
+- **类型：** `boolean`
+- **默认：** `true`
+
+默认情况下，Vite 会在构建阶段将 `publicDir` 目录中的所有文件复制到 `outDir` 目录中。可以通过设置该选项为 `false` 来禁用该行为。
+
 ## build.reportCompressedSize {#build-reportcompressedsize}
 
 - **类型：** `boolean`

config/server-options.md

@@ -297,10 +297,11 @@ export default defineConfig({
 ## server.fs.deny {#server-fs-deny}
 
 - **类型：** `string[]`
+- **类型：** `['.env', '.env.*', '*.{pem,crt}']`
 
 用于限制 Vite 开发服务器提供敏感文件的黑名单。
 
-默认为 `['.env', '.env.*', '*.{pem,crt}']`。
+默认为 `['.env', '.env.*', '*.{pem,crt}']`。这会比 [`server.fs.allow`](#server-fs-allow) 选项的优先级更高。同时还支持 [picomatch patterns](https://github.com/micromatch/picomatch#globbing-features)。
 
 ## server.origin {#server-origin}
 

config/shared-options.md

@@ -158,6 +158,16 @@ Vite 有一个“允许的情景”列表，并且会匹配列表中第一个情
 
 `package.json` 中，在解析包的入口点时尝试的字段列表。注意：这比从 `exports` 字段解析的情景导出优先级低：如果一个入口点从 `exports` 成功解析，`resolve.mainFields` 将被忽略。
 
+## resolve.browserField {#resolve-browserfield}
+
+- **类型：** `boolean`
+- **默认：** `true`
+- **已废弃**
+
+是否启用对 `browser` 字段的解析。
+
+在未来，`resolve.mainFields` 的默认值会变成 `['browser', 'module', 'jsnext:main', 'jsnext']` 而这个选项将被移除。
+
 ## resolve.extensions {#resolve-extensions}
 
 - **类型：** `string[]`

guide/api-hmr.md

@@ -125,7 +125,19 @@ if (import.meta.hot) {
 
 ## `hot.invalidate()` {#hot-invalidate}
 
-现在调用 `import.meta.hot.invalidate()` 只是重新加载页面。
+一个接收自身的模块可以在运行时意识到它不能处理 HMR 更新，因此需要将更新强制传递给导入者。通过调用 `import.meta.hot.invalidate()`，HMR 服务将使调用方的导入失效，就像调用方不是接收自身的一样。
+
+请注意，你应该总是调用 `import.meta.hot.accept`，即使你打算随后立即调用 `invalidate`，否则 HMR 客户端将不会监听未来对接收自身模块的更改。为了清楚地表达你的意图，我们建议在 `accept` 回调中调用 `invalidate`，例如：
+
+
+```js
+import.meta.hot.accept((module) => {
+  // 你可以使用新的模块实例来决定是否使其失效。
+  if (cannotHandleUpdate(module)) {
+    import.meta.hot.invalidate()
+  }
+})
+```
 
 ## `hot.on(event, cb)` {#hot-onevent-cb}
 
@@ -136,6 +148,7 @@ if (import.meta.hot) {
 - `'vite:beforeUpdate'` 当更新即将被应用时（例如，一个模块将被替换）
 - `'vite:beforeFullReload'` 当完整的重载即将发生时
 - `'vite:beforePrune'` 当不再需要的模块即将被剔除时
+- `'vite:invalidate'` 当使用 `import.meta.hot.invalidate()` 使一个模块失效时
 - `'vite:error'` 当发生错误时（例如，语法错误）
 
 自定义 HMR 事件可以由插件发送。更多细节详见 [handleHotUpdate](./api-plugin#handleHotUpdate)。

guide/api-javascript.md

@@ -117,6 +117,11 @@ interface ViteDevServer {
    * 解决 ssr 错误堆栈信息
    */
   ssrFixStacktrace(e: Error): void
+  /**
+   * 触发模块图中某个模块的 HMR。你可以使用 `server.moduleGraph`
+   * API 来检索要重新加载的模块。如果 `hmr` 是 `false`，则不进行任何操作
+   */
+  reloadModule(module: ModuleNode): Promise<void>
   /**
    * 启动服务器
    */

guide/build.md

@@ -128,6 +128,7 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   build: {
     lib: {
+      // Could also be a dictionary or array of multiple entry points
       entry: resolve(__dirname, 'lib/main.js'),
       name: 'MyLib',
       // the proper extensions will be added
@@ -183,8 +184,30 @@ dist/my-lib.umd.cjs 0.30 KiB / gzip: 0.16 KiB
 }
 ```
 
+或者，如果暴露了多个入口起点：
+
+```json
+{
+  "name": "my-lib",
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/my-lib.cjs",
+  "module": "./dist/my-lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/my-lib.mjs",
+      "require": "./dist/my-lib.cjs"
+    },
+    "./secondary": {
+      "import": "./dist/secondary.mjs",
+      "require": "./dist/secondary.cjs"
+    }
+  }
+}
+```
+
 ::: tip 注意
-如果 `package.json` 不包含 `"type": "module"`，Vite 会生成不同的文件后缀名以兼容 Node.js。`.js` 会变为 `.mjs` 而 `.cjs` 会变为 `.js`.
+如果 `package.json` 不包含 `"type": "module"`，Vite 会生成不同的文件后缀名以兼容 Node.js。`.js` 会变为 `.mjs` 而 `.cjs` 会变为 `.js` 。
 :::
 
 ::: tip 环境变量

guide/features.md

@@ -57,7 +57,7 @@ export type { T }
 
 #### `useDefineForClassFields`
 
-从 Vite v2.5.0 开始，如果 TypeScript 的 target 是 `ESNext`，此选项默认值则为 `true`。这与 [`tsc` v4.3.2 及以后版本的行为](https://github.com/microsoft/TypeScript/pull/42663) 一致。这也是标准的 ECMAScript 的运行时行为。
+从 Vite v2.5.0 开始，如果 TypeScript 的 target 是 `ES2022` 或更高，包括 `ESNext`，则此选项默认值为 `true`。这与 [`tsc` v4.3.2 及以后版本的行为](https://github.com/microsoft/TypeScript/pull/42663) 一致。这也是标准的 ECMAScript 的运行时行为。
 
 但对于那些习惯其他编程语言或旧版本 TypeScript 的开发者来说，这可能是违反直觉的。
 你可以参阅 [TypeScript 3.7 发布日志](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) 中了解更多关于如何兼容的信息。
@@ -71,10 +71,13 @@ export type { T }
 #### 影响构建结果的其他编译器选项 {#other-compiler-options-affecting-the-build-result}
 
 - [`extends`](https://www.typescriptlang.org/tsconfig#extends)
+- [`alwaysStrict`](https://www.typescriptlang.org/tsconfig#alwaysStrict)
 - [`importsNotUsedAsValues`](https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues)
-- [`preserveValueImports`](https://www.typescriptlang.org/tsconfig#preserveValueImports)
+- [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
 - [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
 - [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
+- [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)
+- [`preserveValueImports`](https://www.typescriptlang.org/tsconfig#preserveValueImports)
 
 如果你的代码库很难迁移到 `"isolatedModules": true`，或许你可以尝试通过第三方插件来解决，比如 [rollup-plugin-friendly-type-imports](https://www.npmjs.com/package/rollup-plugin-friendly-type-imports)。但是，这种方式不被 Vite 官方支持。
 

guide/static-deploy.md

@@ -64,7 +64,7 @@ $ npm run preview
 
 2. 在你的项目中，创建一个 `deploy.sh` 脚本，包含以下内容（注意高亮的行，按需使用），运行脚本来部署站点：
 
-   ```bash{13,21,24}
+   ```bash{16,24,27}
    #!/usr/bin/env sh
 
    # 发生错误时终止
@@ -76,11 +76,14 @@ $ npm run preview
    # 进入构建文件夹
    cd dist
 
+   # 放置 .nojekyll 以绕过 Jekyll 的处理。
+   echo > .nojekyll
+   
    # 如果你要部署到自定义域名
    # echo 'www.example.com' > CNAME
 
    git init
-   git checkout -b main
+   git checkout -B main
    git add -A
    git commit -m 'deploy'
 

guide/troubleshooting.md

@@ -76,6 +76,20 @@ import './Foo.js' // 应该为 './foo.js'
 
 同时如果有依赖环，也会发生完全重载。要解决这个问题，请先尝试解决依赖循环。
 
+## 构建 {#build}
+
+### 构建产物因为 CORS 错误无法工作 {#built-file-does-not-work-because-of-cors-error}
+
+如果导出的 HTML 文件是通过 `file` 协议打开的，那么其中的 script 将不会运行，且报告下列错误。
+
+> Access to script at 'file:///foo/bar.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.
+
+> Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///foo/bar.js. (Reason: CORS request not http).
+
+请查看 [释因：CORS 请求不是 HTTP 请求 - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSRequestNotHttp) 了解为什么会发生这种情况的更多信息。
+
+你需要通过 `http` 协议访问该文件。最简单的办法就是使用 `npx vite preview`。
+
 ## 其他 {#others}
 
 ### Syntax Error / Type Error {#syntax-error-type-error-happens}