Merge pull request #1531 from vitejs/sync-93e15e7a-1

docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 93e15e7

Author: thinkasany

config/build-options.md

@@ -162,12 +162,10 @@ npm add -D esbuild
 
 ## build.dynamicImportVarsOptions {#build-dynamicimportvarsoptions}
 
-- **类型：** [`RollupDynamicImportVarsOptions`](https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars#options)
-- **相关内容：** [动态导入](/guide/features#dynamic-import)
+- **类型：** `{ include?: string | RegExp | (string | RegExp)[], exclude?: string | RegExp | (string | RegExp)[] }`
+- **相关内容：** [Dynamic Import](/guide/features#dynamic-import)
 
-传递给 [@rollup/plugin-dynamic-import-vars](https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars) 的选项。
-
-<!-- TODO: we need to have a more detailed explanation here as we no longer use @rollup/plugin-dynamic-import-vars. we should say it's compatible with it though -->
+是否转换带有变量的动态导入。
 
 ## build.lib {#build-lib}
 
@@ -223,9 +221,7 @@ export default defineConfig({
 
 ::: tip
 
-如果你想在构建后的代码中引用许可文件，可以使用 `build.rolldownOptions.output.postBanner` 在文件顶部注入注释。例如：
-
-<!-- TODO: add a link for output.postBanner above to Rolldown's documentation -->
+如果您想在构建的代码中引用许可证文件，可以使用 [`build.rolldownOptions.output.postBanner`](https://rolldown.rs/reference/OutputOptions.postBanner#postbanner) 在文件顶部插入注释。例如：
 
 ```js twoslash [vite.config.js]
 import { defineConfig } from 'vite'

config/dep-optimization-options.md

@@ -53,15 +53,12 @@ export default defineConfig({
 
 ## optimizeDeps.rolldownOptions <NonInheritBadge /> {#optimizedeps-rolldownoptions}
 
-- **类型：** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<``RolldownOptions`, `'input' | 'logLevel' | 'output'> & {
+- **类型：** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`[`RolldownOptions`](https://rolldown.rs/reference/), `'input' | 'logLevel' | 'output'> & {
   output?: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`
-    `RolldownOutputOptions`,
+    [`RolldownOutputOptions`](https://rolldown.rs/reference/),
     `'format' | 'sourcemap' | 'dir' | 'banner'>`
 `}`
 
-<!-- TODO: add link to RolldownOptions -->
-<!-- TODO: add link to RolldownOutputOptions -->
-
 在依赖扫描和优化过程中传递给 Rolldown 的选项。
 
 某些选项进行了省略，因为修改它们与 Vite 的优化方案并不兼容。

config/shared-options.md

@@ -94,9 +94,9 @@ declare const __APP_VERSION__: string
 - **类型：**
   `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`
 
-将会被传递到 `@rollup/plugin-alias` 作为 [entries 的选项](https://github.com/rollup/plugins/tree/master/packages/alias#entries)。也可以是一个对象，或一个 `{ find, replacement, customResolver }` 的数组。
+定义用于替换 `import` 或 `require` 语句中值的别名。其工作方式类似于 [`@rollup/plugin-alias`](https://github.com/rollup/plugins/tree/master/packages/alias)。
 
-<!-- TODO: we need to have a more detailed explanation here as we no longer use @rollup/plugin-alias. we should say it's compatible with it though -->
+条目的顺序很重要，因为最先定义的规则会首先应用。
 
 当使用文件系统路径的别名时，请始终使用绝对路径。相对路径的别名值会原封不动地被使用，因此无法被正常解析。
 
@@ -106,6 +106,40 @@ declare const __APP_VERSION__: string
 如果你已经为 [SSR 外部化的依赖](/guide/ssr.md#ssr-externals) 配置了别名，你可能想要为真实的 `node_modules` 包配别名。[Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) 和 [pnpm](https://pnpm.io/aliases/) 都支持通过 `npm:` 前缀配置别名。
 :::
 
+### Object Format (`Record<string, string>`)
+
+对象格式允许将别名指定为键，并将对应的值指定为实际的导入值。例如：
+
+```js
+resolve: {
+  alias: {
+    utils: '../../../utils',
+    'batman-1.0.0': './joker-1.5.0'
+  }
+}
+```
+
+### Array Format (`Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`)
+
+数组格式允许将别名指定为对象，这对于复杂的键/值对非常有用。
+
+```js
+resolve: {
+  alias: [
+    { find: 'utils', replacement: '../../../utils' },
+    { find: 'batman-1.0.0', replacement: './joker-1.5.0' },
+  ]
+}
+```
+
+当 `find` 是一个正则表达式时，`replacement` 可以使用[替换模式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_string_as_the_replacement)，例如 `$1`。例如，要删除带有扩展名的字符串，可以使用如下模式：
+
+```js
+{ find:/^(.*)\.js$/, replacement: '$1.alias' }
+```
+
+`customResolver` 选项可用于为单个别名提供单独的模块解析。
+
 ## resolve.dedupe {#resolve-dedupe}
 
 - **类型：** `string[]`

guide/api-plugin.md

@@ -1,10 +1,8 @@
 # 插件 API {#plugin-api}
 
-Vite 插件扩展了设计出色的 Rollup 接口，带有一些 Vite 独有的配置项。因此，你只需要编写一个 Vite 插件，就可以同时为开发环境和生产环境工作。
+Vite 插件扩展了 Rolldown 的插件接口，添加了一些 Vite 特有的选项。因此，您只需编写一次 Vite 插件，即可使其同时适用于开发环境和构建环境。
 
-**推荐在阅读下面的章节之前，首先阅读下 [Rollup 插件文档](https://cn.rollupjs.org/plugin-development/)**
-
-<!-- TODO: update the link above to Rolldown's documentation -->
+**建议先阅读 [Rolldown 的插件文档](https://rolldown.rs/apis/plugin-api)，然后再阅读以下章节。**
 
 ## 致插件创作者 {#authoring-a-plugin}
 
@@ -19,12 +17,12 @@ Vite 努力秉承开箱即用的原则，因此在创作一款新插件前，请
 
 ## 约定 {#conventions}
 
-如果插件不使用 Vite 特有的钩子，可以作为 [兼容 Rollup 的插件](#rollup-plugin-compatibility) 来实现，推荐使用 [Rollup 插件名称约定](https://cn.rollupjs.org/plugin-development/#conventions)。
+如果插件不使用 Vite 特定的钩子，并且可以作为 [兼容的 Rolldown 插件](#rolldown-plugin-compatibility) 实现，则建议使用 [Rolldown 插件命名约定](https://rolldown.rs/apis/plugin-api#conventions)。
 
-- Rollup 插件应该有一个带 `rollup-plugin-` 前缀、语义清晰的名称。
-- 在 package.json 中包含 `rollup-plugin` 和 `vite-plugin` 关键字。
+- Rolldown 插件应该有一个带 `rolldown-plugin-` 前缀、语义清晰的名称。
+- 在 package.json 的 `keywords` 字段中包含 `rolldown-plugin` 和 `vite-plugin` 关键字。
 
-这样，插件也可以用于纯 Rollup 或基于 WMR 的项目。
+这样，插件也可以用于纯 Rollup 或基于 Rollup 的项目。
 
 对于 Vite 专属的插件：
 
@@ -79,7 +77,7 @@ export default defineConfig({
 ## 简单示例 {#simple-examples}
 
 :::tip
-通常的惯例是创建一个 Vite/Rollup 插件作为一个返回实际插件对象的工厂函数。该函数可以接受允许用户自定义插件行为的选项。
+通常的惯例是创建一个 Vite/Rolldown/Rollup 插件作为一个返回实际插件对象的工厂函数。该函数可以接受允许用户自定义插件行为的选项。
 :::
 
 ### 转换自定义文件类型 {#transforming-custom-file-types}
@@ -140,37 +138,37 @@ import { msg } from 'virtual:my-module'
 console.log(msg)
 ```
 
-虚拟模块在 Vite（以及 Rollup）中都以 `virtual:` 为前缀，作为面向用户路径的一种约定。如果可能的话，插件名应该被用作命名空间，以避免与生态系统中的其他插件发生冲突。举个例子，`vite-plugin-posts` 可以要求用户导入一个 `virtual:posts` 或者 `virtual:posts/helpers` 虚拟模块来获得编译时信息。在内部，使用了虚拟模块的插件在解析时应该将模块 ID 加上前缀 `\0`，这一约定来自 rollup 生态。这避免了其他插件尝试处理这个 ID（比如 node 解析），而例如 sourcemap 这些核心功能可以利用这一信息来区别虚拟模块和正常文件。`\0` 在导入 URL 中不是一个被允许的字符，因此我们需要在导入分析时替换掉它们。一个虚拟 ID 为 `\0{id}` 在浏览器中开发时，最终会被编码为 `/@id/__x00__{id}`。这个 id 会被解码回进入插件处理管线前的样子，因此这对插件钩子的代码是不可见的。
+虚拟模块在 Vite（以及 Rolldown/ Rollup）中都以 `virtual:` 为前缀，作为面向用户路径的一种约定。如果可能的话，插件名应该被用作命名空间，以避免与生态系统中的其他插件发生冲突。举个例子，`vite-plugin-posts` 可以要求用户导入一个 `virtual:posts` 或者 `virtual:posts/helpers` 虚拟模块来获得编译时信息。在内部，使用了虚拟模块的插件在解析时应该将模块 ID 加上前缀 `\0`，这一约定来自 rollup 生态。这避免了其他插件尝试处理这个 ID（比如 node 解析），而例如 sourcemap 这些核心功能可以利用这一信息来区别虚拟模块和正常文件。`\0` 在导入 URL 中不是一个被允许的字符，因此我们需要在导入分析时替换掉它们。一个虚拟 ID 为 `\0{id}` 在浏览器中开发时，最终会被编码为 `/@id/__x00__{id}`。这个 id 会被解码回进入插件处理管线前的样子，因此这对插件钩子的代码是不可见的。
 
 请注意，直接从真实文件派生出来的模块，就像单文件组件中的脚本模块（如.vue 或 .svelte SFC）不需要遵循这个约定。SFC 通常在处理时生成一组子模块，但这些模块中的代码可以映射回文件系统。对这些子模块使用 `\0` 会使 sourcemap 无法正常工作。
 
 ## 通用钩子 {#universal-hooks}
 
-在开发中，Vite 开发服务器会创建一个插件容器来调用 [Rollup 构建钩子](https://cn.rollupjs.org/plugin-development/#build-hooks)，与 Rollup 如出一辙。
+在开发中，Vite 开发服务器会创建一个插件容器来调用 [Rolldown 构建钩子](https://rolldown.rs/apis/plugin-api#build-hooks)，与 Rolldown 如出一辙。
 
 以下钩子在服务器启动时被调用：
 
-- [`options`](https://cn.rollupjs.org/plugin-development/#options)
-- [`buildStart`](https://cn.rollupjs.org/plugin-development/#buildstart)
+- [`options`](https://rolldown.rs/reference/interface.plugin#options)
+- [`buildStart`](https://rolldown.rs/reference/Interface.Plugin#buildstart)
 
 以下钩子会在每个传入模块请求时被调用：
 
-- [`resolveId`](https://cn.rollupjs.org/plugin-development/#resolveid)
-- [`load`](https://cn.rollupjs.org/plugin-development/#load)
-- [`transform`](https://cn.rollupjs.org/plugin-development/#transform)
+- [`resolveId`](https://rolldown.rs/reference/Interface.Plugin#resolveid)
+- [`load`](https://rolldown.rs/reference/Interface.Plugin#load)
+- [`transform`](https://rolldown.rs/reference/Interface.Plugin#transform)
 
 它们还有一个扩展的 `options` 参数，包含其他特定于 Vite 的属性。你可以在 [SSR 文档](/guide/ssr#ssr-specific-plugin-logic) 中查阅更多内容。
 
 一些 `resolveId` 调用的 `importer` 值可能是根目录下的通用 `index.html` 的绝对路径，这是由于 Vite 非打包的开发服务器模式无法始终推断出实际的导入者。对于在 Vite 的解析管道中处理的导入，可以在导入分析阶段跟踪导入者，提供正确的 `importer` 值。
 
 以下钩子在服务器关闭时被调用：
 
-- [`buildEnd`](https://cn.rollupjs.org/plugin-development/#buildend)
-- [`closeBundle`](https://cn.rollupjs.org/plugin-development/#closebundle)
+- [`buildEnd`](https://rolldown.rs/reference/Interface.Plugin#buildend)
+- [`closeBundle`](https://rolldown.rs/reference/Interface.Plugin#closebundle)
 
-请注意 [`moduleParsed`](https://cn.rollupjs.org/plugin-development/#moduleparsed) 钩子在开发中是 **不会** 被调用的，因为 Vite 为了性能会避免完整的 AST 解析。
+请注意 [`moduleParsed`](https://rolldown.rs/reference/Interface.Plugin#moduleparsed) 钩子在开发中是 **不会** 被调用的，因为 Vite 为了性能会避免完整的 AST 解析。
 
-[Output Generation Hooks](https://cn.rollupjs.org/plugin-development/#output-generation-hooks)（除了 `closeBundle`) 在开发中是 **不会** 被调用的。你可以认为 Vite 的开发服务器只调用了 `rollup.rollup()` 而没有调用 `bundle.generate()`。
+[Output Generation Hooks](https://rolldown.rs/apis/plugin-api#output-generation-hooks) （`closeBundle` 除外）在开发期间**不会**被调用。
 
 ## Vite 独有钩子 {#vite-specific-hooks}
 
@@ -485,8 +483,7 @@ Vite 插件也可以提供钩子来服务于特定的 Vite 目标。这些钩子
 - 带有 `enforce: 'post'` 的用户插件
 - Vite 后置构建插件（最小化，manifest，报告）
 
-请注意，这与钩子的排序是分开的，钩子的顺序仍然会受到它们的 `order` 属性的影响，这一点 [和 Rollup 钩子的表现一样](https://cn.rollupjs.org/plugin-development/#build-hooks)。
-
+请注意，这与钩子排序是分开的，钩子仍然像往常一样单独受其 [`order` 属性](https://rolldown.rs/reference/TypeAlias.ObjectHook#order) 的约束。
 ## 情景应用 {#conditional-application}
 
 默认情况下插件在开发（serve）和构建（build）模式中都会调用。如果插件只需要在预览或构建期间有条件地应用，请使用 `apply` 属性指明它们仅在 `'build'` 或 `'serve'` 模式时调用：
@@ -509,21 +506,22 @@ apply(config, { command }) {
 }
 ```
 
-## Rollup 插件兼容性 {#rollup-plugin-compatibility}
+## Rolldown 插件兼容性 {#rolldown-plugin-compatibility}
 
-相当数量的 Rollup 插件将直接作为 Vite 插件工作（例如：`@rollup/plugin-alias` 或 `@rollup/plugin-json`），但并不是所有的，因为有些插件钩子在非构建式的开发服务器上下文中没有意义。
+相当数量的 Rolldown / Rollup 插件将直接作为 Vite 插件工作（例如：`@rollup/plugin-alias` 或 `@rollup/plugin-json`），但并不是所有的，因为有些插件钩子在非构建式的开发服务器上下文中没有意义。
 
-一般来说，只要 Rollup 插件符合以下标准，它就应该像 Vite 插件一样工作：
+一般来说，只要 Rolldown / Rollup 插件符合以下标准，它就应该像 Vite 插件一样工作：
 
-- 没有使用 [`moduleParsed`](https://cn.rollupjs.org/plugin-development/#moduleparsed) 钩子。
+- 它不使用 `moduleParsed` 钩子。
+- 它不依赖 Rolldown 特有的选项，例如 `transform.inject`。
 - 它在打包钩子和输出钩子之间没有很强的耦合。
 
-如果一个 Rollup 插件只在构建阶段有意义，则在 `build.rollupOptions.plugins` 下指定即可。它的工作原理与 Vite 插件的 `enforce: 'post'` 和 `apply: 'build'` 相同。
+如果一个 Rolldown / Rollup 插件只在构建阶段有意义，则在 `build.rolldownOptions.plugins` 下指定即可。它的工作原理与 Vite 插件的 `enforce: 'post'` 和 `apply: 'build'` 相同。
 
-你也可以用 Vite 独有的属性来扩展现有的 Rollup 插件:
+你也可以用 Vite 独有的属性来扩展现有的 Rolldown / Rollup 插件:
 
 ```js [vite.config.js]
-import example from 'rollup-plugin-example'
+import example from 'rolldown-plugin-example'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
@@ -556,7 +554,7 @@ Vite 暴露了 [`@rollup/pluginutils` 的 `createFilter`](https://github.com/rol
 
 ### 钩子过滤功能 {#hook-filters}
 
-Rolldown 引入了[钩子过滤器功能](https://rolldown.rs/plugins/hook-filters) ，以减少 Rust 和 JavaScript 运行时之间的通信开销。此功能允许插件指定确定何时调用钩子的模式，从而通过避免不必要的钩子调用来提高性能。
+Rolldown 引入了[钩子过滤器功能](https://rolldown.rs/apis/plugin-api/hook-filters) ，以减少 Rust 和 JavaScript 运行时之间的通信开销。此功能允许插件指定确定何时调用钩子的模式，从而通过避免不必要的钩子调用来提高性能。
 
 Rollup 4.38.0+ 和 Vite 6.3.0+ 也支持此功能。为了使你的插件向后兼容旧版本，请确保在钩子处理程序中也运行该过滤器。
 

guide/build.md

@@ -52,8 +52,6 @@
 
 构建过程可以通过多种 [构建配置选项](/config/#build-options) 来自定义构建。具体来说，你可以通过 `build.rolldownOptions` 直接调整底层的 [Rolldown 选项](https://rolldown.rs/reference/)：
 
-<!-- TODO: update the link above and below to Rolldown's documentation -->
-
 ```js [vite.config.js]
 export default defineConfig({
   build: {
@@ -86,8 +84,6 @@ window.addEventListener('vite:preloadError', (event) => {
 
 你可以使用 `vite build --watch` 来启用 rollup 的监听器。或者，你可以直接通过 `build.watch` 调整底层的 [`WatcherOptions`](https://rolldown.rs/reference/InputOptions.watch) 选项：
 
-<!-- TODO: update the link above to Rolldown's documentation -->
-
 ```js [vite.config.js]
 export default defineConfig({
   build: {

guide/dep-pre-bundling.md

@@ -57,7 +57,7 @@ export default defineConfig({
 
 `include` 和 `exclude` 都可以用来处理这个问题。如果依赖项很大（包含很多内部模块）或者是 CommonJS，那么你应该包含它；如果依赖项很小，并且已经是有效的 ESM，则可以排除它，让浏览器直接加载它。
 
-你可以通过 [`optimizeDeps.esbuildOptions` 选项](/config/dep-optimization-options.md#optimizedeps-esbuildoptions) 进一步自定义 esbuild。例如，添加一个 esbuild 插件来处理依赖项中的特殊文件，或者更改 [build `target`](https://esbuild.github.io/api/#target)。
+你还可以使用 [`optimizeDeps.rolldownOptions` 选项](/config/dep-optimization-options.md#optimizedeps-rolldownoptions) 进一步自定义 Rolldown。例如，添加 Rolldown 插件来处理依赖项中的特殊文件，或者更改 [构建 `target`](https://rolldown.rs/reference/InputOptions.transform#target)。
 
 <!-- TODO: update the link above to Rolldown's documentation -->
 

guide/features.md

@@ -642,6 +642,14 @@ const module = await import(`./dir/${file}.js`)
 
 注意变量仅代表一层深的文件名。如果 `file` 是 `foo/bar`，导入将会失败。对于更进阶的使用详情，你可以使用 [glob 导入](#glob-import) 功能。
 
+另请注意，动态导入必须符合以下规则才能被打包：
+
+- 导入语句必须以 `./` 或 `../` 开头：``import(`./dir/${foo}.js`)`` 有效，但 ``import(`${foo}.js`)`` 无效。
+- 导入语句必须以文件扩展名结尾：``import(`./dir/${foo}.js`)`` 有效，但 ``import(`./dir/${foo}`)`` 无效。
+- 导入到自身目录时，必须指定文件名模式：``import(`./prefix-${foo}.js`)`` 有效，但 ``import(`./${foo}.js`)`` 无效。
+
+这些规则旨在防止意外导入不应打包的文件。例如，如果没有这些规则，`import(foo)` 会将文件系统中的所有内容都打包。
+
 ## WebAssembly {#webassembly}
 
 预编译的 `.wasm` 文件可以通过 `?init` 来导入。