diff --git a/.vitepress/config.ts b/.vitepress/config.ts index f092f04b..eb67eaa9 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -160,7 +160,7 @@ export default defineConfig({ ], search: { - provider: 'local', + provider: 'local', options: { translations: { button: { @@ -348,7 +348,7 @@ export default defineConfig({ link: '/guide/rolldown', }, { - text: '从 v5 迁移', + text: '从 v6 迁移', link: '/guide/migration', }, { diff --git a/config/ssr-options.md b/config/ssr-options.md index b3d5dd65..0c132ed5 100644 --- a/config/ssr-options.md +++ b/config/ssr-options.md @@ -54,7 +54,7 @@ SSR 服务器的构建目标。 ::: -### ssr.resolve.mainFields +## ssr.resolve.mainFields - **类型：** `string[]` - **默认：** `['module', 'jsnext:main', 'jsnext']` diff --git a/guide/migration.md b/guide/migration.md index 90602742..63b4732f 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -1,154 +1,58 @@ -# 从 v5 迁移 {#migration-from-v5} +# 从 v6 迁移 {#migration-from-v6} -## 环境 API {#environment-api} +## Node.js 支持 {#node-js-support} -作为新的实验性 [环境 API](/guide/api-environment.md) 的一部分，我们进行了大规模的内部重构。Vite 6 努力避免引入破坏性的变更，以确保大多数项目能够快速升级到新的主要版本。我们会等待大部分的生态系统迁移并稳定后，再开始推荐使用新的 API。可能会有一些边缘情况，但这些应该只会影响到框架和工具的底层使用。我们已经与生态系统中的维护者合作，在发布前减轻了这些差异。如果你发现了回退性问题，请 [新建 issue](https://github.com/vitejs/vite/issues/new?assignees=&labels=pending+triage&projects=&template=bug_report.yml)。 +Vite 不再支持已结束生命周期（EOL）的 Node.js 18。现在需要使用 Node.js 20.19+ 或 22.12+。 -由于 Vite 的实现发生了改变，一些内部的 API 已经被移除了。如果你依赖于其中的某一个，那么请创建一个 [feature request](https://github.com/vitejs/vite/issues/new?assignees=&labels=enhancement%3A+pending+triage&projects=&template=feature_request.yml)。 +## 默认浏览器目标变更 {#default-browser-target-change} -## Vite Runtime API {#vite-runtime-api} +`build.target` 的默认浏览器目标已更新为更新的浏览器版本。 -实验性的 Vite Runtime API 已经演变为模块运行器 API（Module Runner API），这是作为新的实验性 [环境 API](/guide/api-environment) 的一部分，在 Vite 6 中发布。鉴于这个功能是实验性的，所以在 Vite 5.1 中引入的先前 API 的移除并不是一个破坏性的更改，但是用户在迁移到 Vite 6 的过程中，需要将他们的使用方式更新为与模块运行器相等的方式。 +- Chrome 87 → 107 +- Edge 88 → 107 +- Firefox 78 → 104 +- Safari 14.0 → 16.0 -## 总体变化 {#general-changes} - -### `resolve.conditions` 的默认值 {#default-value-for-resolve-conditions} - -此更改不会影响未配置 [`resolve.conditions`](/config/shared-options#resolve-conditions) / [`ssr.resolve.conditions`](/config/ssr-options#ssr-resolve-conditions) / [`ssr.resolve.externalConditions`](/config/ssr-options#ssr-resolve-externalconditions) 的用户。 - -在 Vite 5 中，`resolve.conditions` 的默认值是 `[]`，某些条件是内部添加的。`ssr.resolve.conditions` 的默认值是 `resolve.conditions` 的值。 - -从 Vite 6 开始，部分条件不再在内部添加，需要包含在配置值中。 -不再在内部添加的条件为 - -- `resolve.conditions` 是 `['module', 'browser', 'development|production']` -- `ssr.resolve.conditions` 是 `['module', 'node', 'development|production']` - -这些选项的默认值会更新为相应的值，`ssr.resolve.conditions` 不再使用 `resolve.conditions` 作为默认值。请注意，`development|production`是一个特殊变量，会根据 `process.env.NODE_ENV` 的值被替换为 `production` 或 `development`。这些默认值从 `vite` 导出为 `defaultClientConditions` 和 `defaultServerConditions`。 - -如果为 `resolve.conditions` 或 `ssr.resolve.conditions` 指定了自定义值，则需要更新该值以包含新条件。 -例如，如果先前为 `resolve.conditions` 指定了 `['custom']`，那么现在就需要指定 `['custom', ...defaultClientConditions]`。 - -### JSON stringify - -在 Vite 5 中，当设置 [`json.stringify: true`](/config/shared-options#json-stringify) 时，[`json.namedExports`](/config/shared-options#json-namedexports) 会被禁用。 - -从 Vite 6 开始，即使设置了 `json.stringify: true`，`json.namedExports` 也不会被禁用。如果希望实现以前的行为，可以设置 `json.namedExports: false`。 - -Vite 6 还为 `json.stringify` 引入了一个新的默认值，即 `'auto'`，它只会对大型 JSON 文件进行字符串化处理。要禁用此行为，请设置 `json.stringify: false`。 +这些浏览器版本符合 [Baseline](https://web-platform-dx.github.io/web-features/) 在 2025-05-01 时定义的“广泛可用”功能集标准。换句话说，它们的发布日期都在 2022-11-01 之前。 -### 在 HTML 元素中扩展对资源引用的支持 {#extended-support-of-asset-references-in-html-elements} +在 Vite 5 中，默认目标名为 `'modules'`，但现在该选项已不再可用。取而代之的是引入了一个新的默认目标 `'baseline-widely-available'`。 -在 Vite 5 中，只有少数支持的 HTML 元素能够引用由 Vite 处理和打包的资源，如``、`` 等。 - -Vite 6 扩展了对更多 HTML 元素的支持。完整列表请参见 [HTML 功能介绍](/guide/features.html#html) 文档。 - -要在某些元素上选择不进行 HTML 处理，可以在元素上添加 `vite-ignore` 属性。 - -### postcss-load-config - -[`postcss-load-config`](https://npmjs.com/package/postcss-load-config) 已从 v4 更新至 v6。现在需要 [`tsx`](https://www.npmjs.com/package/tsx) 或 [`jiti`](https://www.npmjs.com/package/jiti) 来加载 TypeScript postcss 配置文件，而非 [`ts-node`](https://www.npmjs.com/package/ts-node)。此外，现在需要 [`yaml`](https://www.npmjs.com/package/yaml) 来加​​载 YAML postcss 配置文件。 - -### Sass 现在默认使用现代 API {#sass-now-uses-modern-api-by-default} - -在 Vite 5 中，Sass 默认使用传统 API。Vite 5.4 增加了对现代 API 的支持。 - -从 Vite 6 开始，Sass 默认使用现代 API。如果想继续使用传统 API，可以设置 [`css.preprocessorOptions.sass.api: 'legacy'` / `css.preprocessorOptions.scss.api: 'legacy'`](/config/shared-options#css-preprocessoroptions)。但请注意，传统 API 支持将在 Vite 7 中移除。 - -要迁移到现代 API，请参阅 [Sass 文档](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/)。 - -### 在 library 模式下自定义 CSS 输出文件名 {#customize-css-output-file-name-in-library-mode} - -在 Vite 5 中，library 模式下的 CSS 输出文件名始终是 `style.css`，无法通过 Vite 配置轻松更改。 +## 总体变化 {#general-changes} -从 Vite 6 开始，默认文件名将使用 `package.json` 中的 `"name"`，与 JS 输出文件类似。如果 [`build.lib.fileName`](/config/build-options.md#build-lib) 设置为字符串，该值也将用于 CSS 输出文件名。要明确设置不同的 CSS 文件名，可以使用新的 [`build.lib.cssFileName`](/config/build-options.md#build-lib) 进行配置。 +### 移除了 Sass 旧版 API 支持 {#removed-sass-old-api-support} -迁移时，如果您依赖于 `style.css` 文件名，则应根据软件包名称将对该文件的引用更新为新名称。例如: +如计划所述，Sass 旧版 API 的支持已被移除。Vite 现在仅支持现代 API。你可以移除 `css.preprocessorOptions.sass.api` 和 `css.preprocessorOptions.scss.api` 配置选项。 -```json [package.json] -{ - "name": "my-lib", - "exports": { - "./style.css": "./dist/style.css" // [!code --] - "./style.css": "./dist/my-lib.css" // [!code ++] - } -} -``` +## 移除了已弃用的功能 {#removed-deprecated-features} -如果你更喜欢像在 Vite 5 中那样使用 `style.css`，可以设置 `build.lib.cssFileName: 'style'`。 +- `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.) 接口保持一致。 + - 应使用 `order` 替代 `enforce`，使用 `handler` 替代 `transform`。 ## 进阶 {#advanced} 还有其他一些只影响少数用户的破坏性更改。 -- [[#17922] fix(css)!: remove default import in ssr dev](https://github.com/vitejs/vite/pull/17922) - - 对 CSS 文件默认导入的支持在 Vite 4 中[已被弃用](https://v4.vite.dev/guide/migration.html#importing-css-as-a-string)，并在 Vite 5 中被移除，但在 SSR 开发模式中仍被无意支持。现在该支持已被移除。 -- [[#15637] fix!: default `build.cssMinify` to `'esbuild'` for SSR](https://github.com/vitejs/vite/pull/15637) - - [`build.cssMinify`](/config/build-options#build-cssminify) 现在即使是 SSR 版本也默认为启用。 -- [[#18070] feat!: proxy bypass with WebSocket](https://github.com/vitejs/vite/pull/18070) - - `server.proxy[path].bypass` 现在用于 WebSocket 升级请求，在这种情况下，`res` 参数将是 `undefined`。 -- [[#18209] refactor!: bump minimal terser version to 5.16.0](https://github.com/vitejs/vite/pull/18209) - - [`build.minify: 'terser'`](/config/build-options#build-minify) 所支持的最小 terser 版本从 5.4.0 提升至 5.16.0 -- [[#18231] chore(deps): update dependency @rollup/plugin-commonjs to v28](https://github.com/vitejs/vite/pull/18231) - - [`commonjsOptions.strictRequires`](https://github.com/rollup/plugins/blob/master/packages/commonjs/README.md#strictrequires) 现在默认为 `true`（之前为 `'auto'`）。 - - 这可能会导致包的大小增大，但会使构建更加确定。 - - 如果将 CommonJS 文件指定为入口点，则可能需要额外的步骤。阅读 [commonjs plugin 文档](https://github.com/rollup/plugins/blob/master/packages/commonjs/README.md#using-commonjs-files-as-entry-points) 了解更多详情. -- [[#18243] chore(deps)!: migrate `fast-glob` to `tinyglobby`](https://github.com/vitejs/vite/pull/18243) - - globs 中不再支持范围大括号 (`{01..03}` ⇒ `['01', '02', '03']`) 和递增大括号 (`{2..8..2}` ⇒ `['2', '4', '6', '8']`) 。 -- [[#18395] feat(resolve)!: allow removing conditions](https://github.com/vitejs/vite/pull/18395) - - 此 PR 不仅引入了上文提到的 " `resolve.conditions` 的默认值" 这一破坏性变更，还使得在 SSR 中，`resolve.mainFields` 不能用于无外部化依赖关系。如果您正在使用 `resolve.mainFields`，并希望将其应用于 SSR 中的无外部化依赖关系，您可以使用 [`ssr.resolve.mainFields`](/config/ssr-options#ssr-resolve-mainfields)。 -- [[#18493] refactor!: remove fs.cachedChecks option](https://github.com/vitejs/vite/pull/18493) - - 由于在缓存文件夹中写入文件并立即导入时会出现边缘情况，因此删除了这一选择优化。 -- ~~[[#18697] fix(deps)!: update dependency dotenv-expand to v12](https://github.com/vitejs/vite/pull/18697)~~ - - ~~插值中使用的变量应在插值之前声明。更多详情，请参阅 [`dotenv-expand` changelog](https://github.com/motdotla/dotenv-expand/blob/v12.0.1/CHANGELOG.md#1200-2024-11-16)。~~ 此重大变化已在 v6.1.0 中恢复。 -- [[#16471] feat: v6 - Environment API](https://github.com/vitejs/vite/pull/16471) - - - 对仅 SSR 模块的更新不再触发客户端的页面重载。要恢复以前的行为，可使用自定义 Vite 插件： -
- 点击展开示例 - - ```ts twoslash - import type { Plugin, EnvironmentModuleNode } from 'vite' - - function hmrReload(): Plugin { - return { - name: 'hmr-reload', - enforce: 'post', - hotUpdate: { - order: 'post', - handler({ modules, server, timestamp }) { - if (this.environment.name !== 'ssr') return - - let hasSsrOnlyModules = false - - const invalidatedModules = new Set() - for (const mod of modules) { - if (mod.id == null) continue - const clientModule = - server.environments.client.moduleGraph.getModuleById(mod.id) - if (clientModule != null) continue - - this.environment.moduleGraph.invalidateModule( - mod, - invalidatedModules, - timestamp, - true, - ) - hasSsrOnlyModules = true - } - - if (hasSsrOnlyModules) { - server.ws.send({ type: 'full-reload' }) - return [] - } - }, - }, - } - } - ``` - -
- -## 从 v4 迁移 {#migration-from-v4} - -在 Vite v5 文档中查看 [从 v4 迁移指南](https://v5.vite.dev/guide/migration.html)（[中文版](/guide/migration-from-v4)），了解如何将你的应用迁移到 Vite v5，然后再处理本页中所提及的变化。 +- [[#19979] chore: declare version range for peer dependencies](https://github.com/vitejs/vite/pull/19979) + - 为 CSS 预处理器指定了 peerDependencies 的版本范围。 +- [[#20013] refactor: remove no-op `legacy.proxySsrExternalModules`](https://github.com/vitejs/vite/pull/20013) + - `legacy.proxySsrExternalModules` 属性自 Vite 6 起已无实际作用，现已移除。 +- [[#19985] refactor!: remove deprecated no-op type only properties](https://github.com/vitejs/vite/pull/19985) + - 以下未使用的属性现已移除：`ModuleRunnerOptions.root`、`ViteDevServer._importGlobMap`、`ResolvePluginOptions.isFromTsImporter`、`ResolvePluginOptions.getDepsOptimizer`、`ResolvePluginOptions.shouldExternalize`、`ResolvePluginOptions.ssrConfig` +- [[#19986] refactor: remove deprecated env api properties](https://github.com/vitejs/vite/pull/19986) + - 这些属性从一开始就被标记为弃用，现已移除。 +- [[#19987] refactor!: remove deprecated `HotBroadcaster` related types](https://github.com/vitejs/vite/pull/19987) + - 这些类型是作为现已弃用的 Runtime API 的一部分引入的，现已被移除：`HMRBroadcaster`、`HMRBroadcasterClient`、`ServerHMRChannel`、`HMRChannel`。 +- [[#19996] fix(ssr)!: don't access `Object` variable in ssr transformed code](https://github.com/vitejs/vite/pull/19996) + - `__vite_ssr_exportName__` 现在是模块运行时上下文中的必需字段。 +- [[#20045] fix: treat all `optimizeDeps.entries` values as globs](https://github.com/vitejs/vite/pull/20045) + - `optimizeDeps.entries` 不再接收字面量字符串路径，而是始终接收 glob 模式。 +- [[#20222] feat: apply some middlewares before `configureServer` hook](https://github.com/vitejs/vite/pull/20222), [[#20224] feat: apply some middlewares before `configurePreviewServer` hook](https://github.com/vitejs/vite/pull/20224) + - 某些中间件现在会在 `configureServer` / `configurePreviewServer` 钩子之前被应用。请注意，如果你不希望某个路由应用 [`server.cors`](../config/server-options.md#server-cors) / [`preview.cors`](../config/preview-options.md#preview-cors) 配置，请务必从响应中移除相关的请求头。 + +## 从 v5 迁移 {#migration-from-v5} + +请先查阅 Vite v6 文档中的 [从 v5 迁移指南](https://v6.vite.dev/guide/migration.html)，了解将你的应用迁移到 Vite 6 所需的变更，然后再继续执行本页中的相关更改。