docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 836c818

Author: ShenQingchuan

config/build-options.md

@@ -17,21 +17,55 @@
 
 注意：如果代码包含不能被 `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` 函数对依赖项列表及其路径进行细粒度控制。它期望接收一个 `resolvemodulepreloaddependciesfn` 类型的函数:
+
+```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}
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **Deprecated** use `build.modulePreload.polyfill` instead
+
+Whether to automatically inject a [module preload polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill).
+
 ## build.outDir {#build-outdir}
 
 - **类型：** `string`

guide/api-plugin.md

@@ -594,12 +594,21 @@ export default defineConfig({
 
 ```ts
 // events.d.ts
-import 'vite/types/customEvent'
+import 'vite'
+import 'vite/client/types'
 
-declare module 'vite/types/customEvent' {
-  interface CustomEventMap {
-    'custom:foo': { msg: string }
-    // 'event-key': payload
-  }
+interface MyCustomEventMap {
+  'custom:foo': { msg: string }
+  // 'event-key': payload
+}
+
+// extend interface for server-side
+declare module 'vite' {
+  interface CustomEventMap extends MyCustomEventMap {}
+}
+
+// extend interface for client-side
+declare module 'vite/client/types' {
+  interface CustomEventMap extends MyCustomEventMap {}
 }
 ```

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,6 +76,9 @@ $ npm run preview
    # 进入构建文件夹
    cd dist
 
+   # 放置 .nojekyll 以绕过 Jekyll 的处理。
+   echo > .nojekyll
+   
    # 如果你要部署到自定义域名
    # echo 'www.example.com' > CNAME
 

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}