diff --git a/config/dep-optimization-options.md b/config/dep-optimization-options.md index a6f1984b..221f09af 100644 --- a/config/dep-optimization-options.md +++ b/config/dep-optimization-options.md @@ -51,7 +51,7 @@ export default defineConfig({ }) ``` -## optimizeDeps.esbuildOptions {#optimizedeps-esbuild-options} +## optimizeDeps.esbuildOptions {#optimizedeps-esbuildoptions} - **类型：** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`[`EsbuildBuildOptions`](https://esbuild.github.io/api/#general-options)`, | 'bundle' @@ -78,7 +78,7 @@ export default defineConfig({ 设置为 `true` 可以强制依赖预构建，而忽略之前已经缓存过的、已经优化过的依赖。 -## optimizeDeps.noDiscovery {#optimizedeps-no-discovery} +## optimizeDeps.noDiscovery {#optimizedeps-nodiscovery} - **类型：** `boolean` - **默认：** `false` diff --git a/guide/api-environment-frameworks.md b/guide/api-environment-frameworks.md index f9e8dabd..5b338475 100644 --- a/guide/api-environment-frameworks.md +++ b/guide/api-environment-frameworks.md @@ -13,7 +13,7 @@ 请与我们分享您的反馈。 ::: -## 开发环境通信级别 +## 开发环境通信级别 {#devenvironment-communication-levels} 由于环境可能在不同的运行时环境中运行，与环境的通信可能会受到运行时环境的限制。为了使框架能够轻松编写与运行时环境无关的代码，环境 API 提供了三种通信级别。 @@ -142,7 +142,7 @@ const server = await createServer({ createEnvironment(name, config) { return createFetchableDevEnvironment(name, config, { handleRequest(request: Request): Promise | Response { - // 处理请求和返回响应 + // 处理请求和返回响应 }, }) }, diff --git a/guide/api-hmr.md b/guide/api-hmr.md index a4b8b7bd..23a7ce71 100644 --- a/guide/api-hmr.md +++ b/guide/api-hmr.md @@ -184,7 +184,7 @@ import.meta.hot.data = { someValue: 'hello' } 目前是一个空操作并暂留用于向后兼容。若有新的用途设计可能在未来会发生变更。要指明某模块是不可热更新的，请使用 `hot.invalidate()`。 -## `hot.invalidate(message?: string)` {#hot-invalidate} +## `hot.invalidate(message?: string)` {#hot-invalidate-message-string} 一个接收自身的模块可以在运行时意识到它不能处理 HMR 更新，因此需要将更新强制传递给导入者。通过调用 `import.meta.hot.invalidate()`，HMR 服务将使调用方的导入失效，就像调用方不是接收自身的一样。这会同时在浏览器控制台和命令行中打印出一条信息，你可以传入这条信息，对发生失效的原因给予一些上下文。 @@ -201,7 +201,7 @@ import.meta.hot.accept((module) => { }) ``` -## `hot.on(event, cb)` {#hot-onevent-cb} +## `hot.on(event, cb)` {#hot-on-event-cb} 监听自定义 HMR 事件。 @@ -218,7 +218,7 @@ import.meta.hot.accept((module) => { 自定义 HMR 事件可以由插件发送。更多细节详见 [handleHotUpdate](./api-plugin#handleHotUpdate)。 -## `hot.off(event, cb)` {#hot-offevent-cb} +## `hot.off(event, cb)` {#hot-off-event-cb} 从事件监听器中移除回调函数。 diff --git a/guide/api-plugin.md b/guide/api-plugin.md index b3e84930..f3a272e2 100644 --- a/guide/api-plugin.md +++ b/guide/api-plugin.md @@ -343,7 +343,7 @@ Vite 插件也可以提供钩子来服务于特定的 Vite 目标。这些钩子 - 一个包含 `{ html, tags }` 的对象 默认情况下 `order` 是 `undefined`，这个钩子会在 HTML 被转换后应用。为了注入一个应该通过 Vite 插件管道的脚本， `order: 'pre'` 指将在处理 HTML 之前应用。 `order: 'post'` 是在所有未定义的 `order` 的钩子函数被应用后才应用。 - + **基础示例：** ```js @@ -657,7 +657,7 @@ export default defineConfig({ }) ``` -### 自定义事件的 TypeScript 类型定义指南 {#typeScript-for-custom-events} +### 自定义事件的 TypeScript 类型定义指南 {#typescript-for-custom-events} Vite 会在内部从 `CustomEventMap` 这个接口推断出 payload 的类型，可以通过扩展这个接口来为自定义事件进行类型定义： diff --git a/guide/env-and-mode.md b/guide/env-and-mode.md index d4b978c0..5a07c866 100644 --- a/guide/env-and-mode.md +++ b/guide/env-and-mode.md @@ -116,7 +116,7 @@ VITE_BAR=bar ::: -## TypeScript 的智能提示 {#intellisense} +## TypeScript 的智能提示 {#intellisense-for-typescript} 默认情况下，Vite 在 [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/client.d.ts) 中为 `import.meta.env` 提供了类型定义。随着在 `.env[mode]` 文件中自定义了越来越多的环境变量，你可能想要在代码中获取这些以 `VITE_` 为前缀的用户自定义环境变量的 TypeScript 智能提示。 diff --git a/guide/migration.md b/guide/migration.md index 8931347b..7d72c7ab 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -8,10 +8,10 @@ Vite 不再支持已结束生命周期（EOL）的 Node.js 18。现在需要使 `build.target` 的默认浏览器值已更新为较新的浏览器版本。 -- Chrome 87 → 107 -- Edge 88 → 107 -- Firefox 78 → 104 -- Safari 14.0 → 16.0 +- Chrome 87 → 107 +- Edge 88 → 107 +- Firefox 78 → 104 +- Safari 14.0 → 16.0 这些浏览器版本符合 [Baseline](https://web-platform-dx.github.io/web-features/) 在 2025-05-01 时定义的“广泛可用”功能集标准。换句话说，它们的发布日期都在 2022-11-01 之前。 @@ -19,17 +19,17 @@ Vite 不再支持已结束生命周期（EOL）的 Node.js 18。现在需要使 ## 总体变化 {#general-changes} -### 移除了 Sass 旧版 API 支持 {#removed-sass-old-api-support} +### 移除了 Sass 旧版 API 支持 {#removed-sass-legacy-api-support} 如计划所述，Sass 旧版 API 的支持已被移除。Vite 现在仅支持现代 API。你可以移除 `css.preprocessorOptions.sass.api` 和 `css.preprocessorOptions.scss.api` 配置选项。 ## 移除了已弃用的功能 {#removed-deprecated-features} -- `splitVendorChunkPlugin`（在 v5.2.7 中弃用） - - 该插件最初是为了方便迁移到 Vite v2.9 而提供的。 +- `splitVendorChunkPlugin`（在 v5.2.7 中弃用） + - 该插件最初是为了方便迁移到 Vite v2.9 而提供的。 - 如有需要，可以使用 `build.rollupOptions.output.manualChunks` 选项来控制分块行为。 -- `transformIndexHtml` 的 hook 级别 `enforce` / `transform`（在 v4.0.0 中弃用） - - 此更改是为了与 [Rollup 的对象型 hooks](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.) 接口保持一致。 +- `transformIndexHtml` 的 hook 级别 `enforce` / `transform`（在 v4.0.0 中弃用） + - 此更改是为了与 [Rollup 的对象型 hooks](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.) 接口保持一致。 - 应使用 `order` 替代 `enforce`，使用 `handler` 替代 `transform`。 ## 进阶 {#advanced} diff --git a/guide/rolldown.md b/guide/rolldown.md index 7f6b3d2d..87e9b8f8 100644 --- a/guide/rolldown.md +++ b/guide/rolldown.md @@ -109,7 +109,7 @@ Rolldown 专注于三个主要原则： ### API 差异 {#api-differences} -#### `manualChunks` 改为 `advancedChunks` {#manualchunks-changed-to-advancedchunks} +#### `manualChunks` 改为 `advancedChunks` {#manualchunks-to-advancedchunks} 虽然 Rolldown 支持与 Rollup 相同的 `manualChunks` 选项，但该选项已被标记为过时。作为替代，Rolldown 通过 [`advancedChunks` 选项](https://rolldown.rs/in-depth/advanced-chunks) 提供更精细的设置，该选项与 webpack 的 `splitChunk` 功能更为相似： @@ -214,7 +214,7 @@ export default defineConfig({ 未来我们将为 Vite 引入全量打包模式（Full Bundle Mode），该模式将在生产环境 _和开发模式_ 下提供打包后的文件。 -### 为何引入全量打包模式？ {#why-introducing-full-bundle-mode} +### 为何引入全量打包模式？ {#why-introducing-a-full-bundle-mode} Vite 以其非打包开发服务器方案著称，这正是其早期凭借速度优势迅速流行的关键原因。这种方案最初是尝试探索在不进行传统打包的情况下，开发服务器性能能达到何种极限。 @@ -299,7 +299,7 @@ if (vite.rolldownVersion) { 可通过条件式传递选项（通过 [如上所示](#detecting-rolldown-vite) 检测是否使用 `rolldown-vite`）来修复此问题。 -### `transformWithEsbuild` 需要单独安装 `esbuild` {#transformwithesbuild-requires-installing-esbuild-separately} +### `transformWithEsbuild` 需要单独安装 `esbuild` {#transformwithesbuild-requires-esbuild-to-be-installed-separately} 由于 Vite 本身已不再使用 `esbuild`，`esbuild` 现在被作为可选的 peer dependency。如果你的插件使用了 `transformWithEsbuild`，则需要将 `esbuild` 添加到插件的依赖中，或者由用户手动安装。 diff --git a/guide/ssr.md b/guide/ssr.md index f476b5c7..b77e4629 100644 --- a/guide/ssr.md +++ b/guide/ssr.md @@ -1,4 +1,4 @@ -# 服务端渲染 (SSR) {#server-side-rendering} +# 服务端渲染 (SSR) {#server-side-rendering-ssr} :::tip 注意 SSR 特别指支持在 Node.js 中运行相同应用程序的前端框架（例如 React、Preact、Vue 和 Svelte），将其预渲染成 HTML，最后在客户端进行水合处理。如果你正在寻找与传统服务器端框架的集成，请查看 [后端集成指南](./backend-integration)。 @@ -221,7 +221,7 @@ const html = await vueServerRenderer.renderToString(app, ctx) 我们现在需要在 `server.js` 的生产环境分支下读取该清单，并将其传递到 `src/entry-server.js` 导出的 `render` 函数中。这将为我们提供足够的信息，来为异步路由相应的文件渲染预加载指令！查看 [示例代码](https://github.com/vitejs/vite-plugin-vue/blob/main/playground/ssr-vue/src/entry-server.js) 获取完整示例。你还可以利用 [103 Early Hints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103) 所提供的信息。 -## 预渲染 / SSG {#pre-rendering--ssg} +## 预渲染 / SSG {#pre-rendering-ssg} 如果预先知道某些路由所需的路由和数据，我们可以使用与生产环境 SSR 相同的逻辑将这些路由预先渲染到静态 HTML 中。这也被视为一种静态站点生成（SSG）的形式。查看 [示例渲染代码](https://github.com/vitejs/vite-plugin-vue/blob/main/playground/ssr-vue/prerender.js) 获取有效示例。 diff --git a/guide/troubleshooting.md b/guide/troubleshooting.md index 5be4044c..bbc9e2d1 100644 --- a/guide/troubleshooting.md +++ b/guide/troubleshooting.md @@ -6,7 +6,7 @@ ## CLI {#cli} -### `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'` {#error-cannot-find-module-cfoobarbazvitebinvitejs} +### `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'` {#error-cannot-find-module-c-foo-bar-baz-vite-bin-vite-js} 你的项目文件夹路径中可能包含了符号 `&`，这在 Windows 上无法与 `npm` 配合正常工作 ([npm/cmd-shim#45](https://github.com/npm/cmd-shim/issues/45))。 @@ -102,7 +102,7 @@ security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain- 要避免这个问题，请尝试减小请求头大小。举个例子，如果 cookie 太长，请删除它。或者你可以使用 [`--max-http-header-size`](https://nodejs.org/api/cli.html#--max-http-header-sizesize) 来更改最大请求头大小。 -### 开发容器 / VS Code 端口转发 +### 开发容器 / VS Code 端口转发 {#dev-containers-vs-code-port-forwarding} 如果你正在使用开发容器或 VS Code 的端口转发功能，可能需要在配置中将 [`server.host`](/config/server-options.md#server-host) 选项设置为 `127.0.0.1` 才能使其正常工作。 @@ -189,7 +189,7 @@ import './Foo.js' // 应该为 './foo.js' 可以通过修改 [`build.rollupOptions.output.chunkFileNames`](../config/build-options.md#build-rollupoptions) 中的块文件名来绕过此问题，因为这些扩展程序通常会根据文件名（例如包含 `ad` 或 `track` 的文件名）来阻止请求。 -## 优化依赖 {#optimize-dependencies} +## 优化依赖 {#optimized-dependencies} ### 链接本地包时过期预构建依赖项 {#outdated-pre-bundled-deps-when-linking-to-a-local-package} diff --git a/guide/why.md b/guide/why.md index 6906d28c..8a1dbaa5 100644 --- a/guide/why.md +++ b/guide/why.md @@ -57,7 +57,7 @@ Vite 目前的插件 API 与使用 `esbuild` 作为打包器并不兼容。尽 Rollup 已经开始着手改进性能，[在 v4 中将其解析器切换到 SWC](https://github.com/rollup/rollup/pull/5073)。同时还有一个正在进行中的工作，即构建一个名为 Rolldown 的 Rust 版本的 Rollup。一旦 Rolldown 准备就绪，它就可以在 Vite 中取代 Rollup 和 esbuild，显著提高构建性能，并消除开发和构建之间的不一致性。你可以观看 [Evan You 在 ViteConf 2023 的主题演讲](https://youtu.be/hrdwQHoAp0M) 了解更多细节。 -## Vite 与其他免打包构建工具的关系是什么？{##how-vite-relates-to-other-unbundled-build-tools} +## Vite 与其他免打包构建工具的关系是什么？{#how-vite-relates-to-other-unbundled-build-tools} Preact 团队的 [WMR](https://github.com/preactjs/wmr) 旨在提供类似的功能集。Vite 用于开发和构建的通用 Rollup 插件 API 就是受其启发。WMR 已经不再维护。Preact 团队现在推荐使用 Vite 和 [@preactjs/preset-vite](https://github.com/preactjs/preset-vite)。