From 59f377e071306ee0105ef5056ac1b54a8cc583b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Mon, 16 Jun 2025 10:18:26 +0900 Subject: [PATCH 1/4] docs: correct heading level in `ssr-options.md` (#20208) --- config/ssr-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/ssr-options.md b/config/ssr-options.md index 0d64c4d7..6f07bba3 100644 --- a/config/ssr-options.md +++ b/config/ssr-options.md @@ -54,7 +54,7 @@ For example, when setting `['node', 'custom']`, you should run `NODE_OPTIONS='-- ::: -### ssr.resolve.mainFields +## ssr.resolve.mainFields - **Type:** `string[]` - **Default:** `['module', 'jsnext:main', 'jsnext']` From d63725c8b820429543943d4f97810e4cb0299aa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0?= Date: Thu, 19 Jun 2025 16:43:54 +0900 Subject: [PATCH 2/4] docs: migration guide for v7 (#20051) Co-authored-by: patak-dev --- .vitepress/config.ts | 2 +- guide/migration.md | 178 ++++++++++--------------------------------- 2 files changed, 42 insertions(+), 138 deletions(-) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index ca4acb08..bcba429a 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -307,7 +307,7 @@ export default defineConfig({ link: '/guide/rolldown', }, { - text: 'Migration from v5', + text: 'Migration from v6', link: '/guide/migration', }, { diff --git a/guide/migration.md b/guide/migration.md index 80d65e96..42daebc4 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -1,154 +1,58 @@ -# Migration from v5 +# Migration from v6 -## Environment API +## Node.js Support -As part of the new experimental [Environment API](/guide/api-environment.md), a big internal refactoring was needed. Vite 6 strives to avoid breaking changes to ensure most projects can quickly upgrade to the new major. We'll wait until a big portion of the ecosystem has moved to stabilize and start recommending the use of the new APIs. There may be some edge cases but these should only affect low level usage by frameworks and tools. We have worked with maintainers in the ecosystem to mitigate these differences before the release. Please [open an issue](https://github.com/vitejs/vite/issues/new?assignees=&labels=pending+triage&projects=&template=bug_report.yml) if you spot a regression. +Vite no longer supports Node.js 18, which reached its EOL. Node.js 20.19+ / 22.12+ is now required. -Some internal APIs have been removed due to changes in Vite's implementation. If you were relying on one of them, please create a [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 +The default browser value of `build.target` is updated to a newer browser. -The experimental Vite Runtime API evolved into the Module Runner API, released in Vite 6 as part of the new experimental [Environment API](/guide/api-environment). Given that the feature was experimental the removal of the previous API introduced in Vite 5.1 isn't a breaking change, but users will need to update their use to the Module Runner equivalent as part of migrating to Vite 6. +- Chrome 87 → 107 +- Edge 88 → 107 +- Firefox 78 → 104 +- Safari 14.0 → 16.0 -## General Changes - -### Default value for `resolve.conditions` - -This change does not affect users that did not configure [`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). - -In Vite 5, the default value for `resolve.conditions` was `[]` and some conditions were added internally. The default value for `ssr.resolve.conditions` was the value of `resolve.conditions`. - -From Vite 6, some of the conditions are no longer added internally and need to be included in the config values. -The conditions that are no longer added internally for - -- `resolve.conditions` are `['module', 'browser', 'development|production']` -- `ssr.resolve.conditions` are `['module', 'node', 'development|production']` - -The default values for those options are updated to the corresponding values and `ssr.resolve.conditions` no longer uses `resolve.conditions` as the default value. Note that `development|production` is a special variable that is replaced with `production` or `development` depending on the value of `process.env.NODE_ENV`. These default values are exported from `vite` as `defaultClientConditions` and `defaultServerConditions`. - -If you specified a custom value for `resolve.conditions` or `ssr.resolve.conditions`, you need to update it to include the new conditions. -For example, if you previously specified `['custom']` for `resolve.conditions`, you need to specify `['custom', ...defaultClientConditions]` instead. - -### JSON stringify - -In Vite 5, when [`json.stringify: true`](/config/shared-options#json-stringify) is set, [`json.namedExports`](/config/shared-options#json-namedexports) was disabled. - -From Vite 6, even when `json.stringify: true` is set, `json.namedExports` is not disabled and the value is respected. If you wish to achieve the previous behavior, you can set `json.namedExports: false`. - -Vite 6 also introduces a new default value for `json.stringify` which is `'auto'`, which will only stringify large JSON files. To disable this behavior, set `json.stringify: false`. +These browser versions align with [Baseline](https://web-platform-dx.github.io/web-features/) Widely Available feature sets as of 2025-05-01. In other words, they were all released before 2022-11-01. -### Extended support of asset references in HTML elements +In Vite 5, the default target was named `'modules'`, but this is no longer available. Instead, a new default target `'baseline-widely-available'` is introduced. -In Vite 5, only a few supported HTML elements were able to reference assets that will be processed and bundled by Vite, such as ``, ``, etc. - -Vite 6 extends the support to even more HTML elements. The full list can be found at the [HTML features](/guide/features.html#html) docs. - -To opt-out of HTML processing on certain elements, you can add the `vite-ignore` attribute on the element. - -### postcss-load-config - -[`postcss-load-config`](https://npmjs.com/package/postcss-load-config) has been updated to v6 from v4. [`tsx`](https://www.npmjs.com/package/tsx) or [`jiti`](https://www.npmjs.com/package/jiti) is now required to load TypeScript postcss config files instead of [`ts-node`](https://www.npmjs.com/package/ts-node). Also [`yaml`](https://www.npmjs.com/package/yaml) is now required to load YAML postcss config files. - -### Sass now uses modern API by default - -In Vite 5, the legacy API was used by default for Sass. Vite 5.4 added support for the modern API. - -From Vite 6, the modern API is used by default for Sass. If you wish to still use the legacy API, you can set [`css.preprocessorOptions.sass.api: 'legacy'` / `css.preprocessorOptions.scss.api: 'legacy'`](/config/shared-options#css-preprocessoroptions). But note that the legacy API support will be removed in Vite 7. - -To migrate to the modern API, see [the Sass documentation](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/). - -### Customize CSS output file name in library mode - -In Vite 5, the CSS output file name in library mode was always `style.css` and cannot be easily changed through the Vite config. +## General Changes -From Vite 6, the default file name now uses `"name"` in `package.json` similar to the JS output files. If [`build.lib.fileName`](/config/build-options.md#build-lib) is set with a string, the value will also be used for the CSS output file name. To explicitly set a different CSS file name, you can use the new [`build.lib.cssFileName`](/config/build-options.md#build-lib) to configure it. +### Removed Sass legacy API support -To migrate, if you had relied on the `style.css` file name, you should update references to it to the new name based on your package name. For example: +As planned, support for the Sass legacy API is removed. Vite now only supports the modern API. You can remove the `css.preprocessorOptions.sass.api` / `css.preprocessorOptions.scss.api` option. -```json [package.json] -{ - "name": "my-lib", - "exports": { - "./style.css": "./dist/style.css" // [!code --] - "./style.css": "./dist/my-lib.css" // [!code ++] - } -} -``` +## Removed deprecated features -If you prefer to stick with `style.css` like in Vite 5, you can set `build.lib.cssFileName: 'style'` instead. +- `splitVendorChunkPlugin` (deprecated in v5.2.7) + - This plugin was originally provided to ease migration to Vite v2.9. + - The `build.rollupOptions.output.manualChunks` option can be used to control the chunking behavior if needed. +- Hook-level `enforce` / `transform` for `transformIndexHtml` (deprecated in v4.0.0) + - It was changed to align the interface with [Rollup's object hooks](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.). + - `order` should be used instead of `enforce`, and `handler` should be used instead of `transform`. ## Advanced There are other breaking changes which only affect few users. -- [[#17922] fix(css)!: remove default import in ssr dev](https://github.com/vitejs/vite/pull/17922) - - Support for default import of CSS files was [deprecated in Vite 4](https://v4.vite.dev/guide/migration.html#importing-css-as-a-string) and removed in Vite 5, but it was still unintentionally supported in SSR dev mode. This support is now removed. -- [[#15637] fix!: default `build.cssMinify` to `'esbuild'` for SSR](https://github.com/vitejs/vite/pull/15637) - - [`build.cssMinify`](/config/build-options#build-cssminify) is now enabled by default even for SSR builds. -- [[#18070] feat!: proxy bypass with WebSocket](https://github.com/vitejs/vite/pull/18070) - - `server.proxy[path].bypass` is now called for WebSocket upgrade requests and in that case, the `res` parameter will be `undefined`. -- [[#18209] refactor!: bump minimal terser version to 5.16.0](https://github.com/vitejs/vite/pull/18209) - - Minimal supported terser version for [`build.minify: 'terser'`](/config/build-options#build-minify) was bumped to 5.16.0 from 5.4.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) is now `true` by default (was `'auto'` before). - - This may lead to larger bundle sizes but will result in more deterministic builds. - - If you are specifying a CommonJS file as an entry point, you may need additional steps. Read [the commonjs plugin documentation](https://github.com/rollup/plugins/blob/master/packages/commonjs/README.md#using-commonjs-files-as-entry-points) for more details. -- [[#18243] chore(deps)!: migrate `fast-glob` to `tinyglobby`](https://github.com/vitejs/vite/pull/18243) - - Range braces (`{01..03}` ⇒ `['01', '02', '03']`) and incremental braces (`{2..8..2}` ⇒ `['2', '4', '6', '8']`) are no longer supported in globs. -- [[#18395] feat(resolve)!: allow removing conditions](https://github.com/vitejs/vite/pull/18395) - - This PR not only introduces a breaking change mentioned above as "Default value for `resolve.conditions`", but also makes `resolve.mainFields` to not be used for no-externalized dependencies in SSR. If you were using `resolve.mainFields` and want to apply that to no-externalized dependencies in SSR, you can use [`ssr.resolve.mainFields`](/config/ssr-options#ssr-resolve-mainfields). -- [[#18493] refactor!: remove fs.cachedChecks option](https://github.com/vitejs/vite/pull/18493) - - This opt-in optimization was removed due to edge cases when writing a file in a cached folder and immediately importing it. -- ~~[[#18697] fix(deps)!: update dependency dotenv-expand to v12](https://github.com/vitejs/vite/pull/18697)~~ - - ~~Variables used in interpolation should be declared before the interpolation now. For more details, see [the `dotenv-expand` changelog](https://github.com/motdotla/dotenv-expand/blob/v12.0.1/CHANGELOG.md#1200-2024-11-16).~~ This breaking change was reverted in v6.1.0. -- [[#16471] feat: v6 - Environment API](https://github.com/vitejs/vite/pull/16471) - - - Updates to an SSR-only module no longer triggers a full page reload in the client. To return to the previous behaviour, a custom Vite plugin can be used: -
- Click to expand example - - ```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 [] - } - }, - }, - } - } - ``` - -
- -## Migration from v4 - -Check the [Migration from v4 Guide](https://v5.vite.dev/guide/migration.html) in the Vite v5 docs first to see the needed changes to port your app to Vite 5, and then proceed with the changes on this page. +- [[#19979] chore: declare version range for peer dependencies](https://github.com/vitejs/vite/pull/19979) + - Specified the peer dependencies version range for CSS preprocessors. +- [[#20013] refactor: remove no-op `legacy.proxySsrExternalModules`](https://github.com/vitejs/vite/pull/20013) + - `legacy.proxySsrExternalModules` property had no effect since Vite 6. It is now removed. +- [[#19985] refactor!: remove deprecated no-op type only properties](https://github.com/vitejs/vite/pull/19985) + - The following unused properties are now removed: `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) + - These properties were deprecated from the beginning. It is now removed. +- [[#19987] refactor!: remove deprecated `HotBroadcaster` related types](https://github.com/vitejs/vite/pull/19987) + - These types were introduced as part of the now-deprecated Runtime API. It is now removed: `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__` is now required for the module runner runtime context. +- [[#20045] fix: treat all `optimizeDeps.entries` values as globs](https://github.com/vitejs/vite/pull/20045) + - `optimizeDeps.entries` now does not receive literal string paths. Instead, it always receives globs. +- [[#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) + - Some middlewares are now applied before the `configureServer` / `configurePreviewServer` hook. Note that if you don't expect a certain route to apply the [`server.cors`](../config/server-options.md#server-cors) / [`preview.cors`](../config/preview-options.md#preview-cors) option, make sure to remove the related headers from the response. + +## Migration from v5 + +Check the [Migration from v5 Guide](https://v6.vite.dev/guide/migration.html) in the Vite v6 docs first to see the needed changes to port your app to Vite 6, and then proceed with the changes on this page. From 586fafd69f379a0a11b2653b345ef94f77635734 Mon Sep 17 00:00:00 2001 From: Kylin <1159469891@qq.com> Date: Fri, 20 Jun 2025 10:07:55 +0800 Subject: [PATCH 3/4] docs: update content --- .vitepress/config.ts | 8 +- guide/migration.md | 215 ++++++------------------------------------- 2 files changed, 32 insertions(+), 191 deletions(-) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index b2cbc7db..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,11 +348,7 @@ export default defineConfig({ link: '/guide/rolldown', }, { -<<<<<<< HEAD - text: '从 v5 迁移', -======= - text: 'Migration from v6', ->>>>>>> d63725c8b820429543943d4f97810e4cb0299aa0 + text: '从 v6 迁移', link: '/guide/migration', }, { diff --git a/guide/migration.md b/guide/migration.md index edef93b1..1ea691b7 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -1,213 +1,58 @@ -<<<<<<< HEAD -# 从 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 的过程中，需要将他们的使用方式更新为与模块运行器相等的方式。 -======= -# Migration from v6 +- Chrome 87 → 107 +- Edge 88 → 107 +- Firefox 78 → 104 +- Safari 14.0 → 16.0 -## Node.js Support +这些浏览器版本符合 [Baseline](https://web-platform-dx.github.io/web-features/) 在 2025-05-01 时定义的“广泛可用”功能集标准。换句话说，它们的发布日期都在 2022-11-01 之前。 -Vite no longer supports Node.js 18, which reached its EOL. Node.js 20.19+ / 22.12+ is now required. - -## Default Browser Target change - -The default browser value of `build.target` is updated to a newer browser. - -- Chrome 87 → 107 -- Edge 88 → 107 -- Firefox 78 → 104 -- Safari 14.0 → 16.0 - -These browser versions align with [Baseline](https://web-platform-dx.github.io/web-features/) Widely Available feature sets as of 2025-05-01. In other words, they were all released before 2022-11-01. - -In Vite 5, the default target was named `'modules'`, but this is no longer available. Instead, a new default target `'baseline-widely-available'` is introduced. ->>>>>>> d63725c8b820429543943d4f97810e4cb0299aa0 +在 Vite 5 中，默认目标名为 `'modules'`，但现在该选项已不再可用。取而代之的是引入了一个新的默认目标 `'baseline-widely-available'`。 ## 总体变化 {#general-changes} -<<<<<<< HEAD -### `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`。 - -### 在 HTML 元素中扩展对资源引用的支持 {#extended-support-of-asset-references-in-html-elements} - -在 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 配置轻松更改。 - -从 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) 进行配置。 - -迁移时，如果您依赖于 `style.css` 文件名，则应根据软件包名称将对该文件的引用更新为新名称。例如: - -```json [package.json] -{ - "name": "my-lib", - "exports": { - "./style.css": "./dist/style.css" // [!code --] - "./style.css": "./dist/my-lib.css" // [!code ++] - } -} -``` - -如果你更喜欢像在 Vite 5 中那样使用 `style.css`，可以设置 `build.lib.cssFileName: 'style'`。 -======= -### Removed Sass legacy API support +### 移除了 Sass 旧版 API 支持 {#removed-sass-old-api-support} -As planned, support for the Sass legacy API is removed. Vite now only supports the modern API. You can remove the `css.preprocessorOptions.sass.api` / `css.preprocessorOptions.scss.api` option. +如计划所述，Sass 旧版 API 的支持已被移除。Vite 现在仅支持现代 API。你可以移除 `css.preprocessorOptions.sass.api` 和 `css.preprocessorOptions.scss.api` 配置选项。 -## Removed deprecated features +## 移除了已弃用的功能 {#removed-deprecated-features} -- `splitVendorChunkPlugin` (deprecated in v5.2.7) - - This plugin was originally provided to ease migration to Vite v2.9. - - The `build.rollupOptions.output.manualChunks` option can be used to control the chunking behavior if needed. -- Hook-level `enforce` / `transform` for `transformIndexHtml` (deprecated in v4.0.0) - - It was changed to align the interface with [Rollup's object hooks](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.). - - `order` should be used instead of `enforce`, and `handler` should be used instead of `transform`. ->>>>>>> d63725c8b820429543943d4f97810e4cb0299aa0 +- `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} 还有其他一些只影响少数用户的破坏性更改。 -<<<<<<< HEAD -- [[#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) - - Specified the peer dependencies version range for CSS preprocessors. + - 为 CSS 预处理器指定了 peerDependencies 的版本范围。 - [[#20013] refactor: remove no-op `legacy.proxySsrExternalModules`](https://github.com/vitejs/vite/pull/20013) - - `legacy.proxySsrExternalModules` property had no effect since Vite 6. It is now removed. + - `legacy.proxySsrExternalModules` 属性自 Vite 6 起已无实际作用，现已移除。 - [[#19985] refactor!: remove deprecated no-op type only properties](https://github.com/vitejs/vite/pull/19985) - - The following unused properties are now removed: `ModuleRunnerOptions.root`, `ViteDevServer._importGlobMap`, `ResolvePluginOptions.isFromTsImporter`, `ResolvePluginOptions.getDepsOptimizer`, `ResolvePluginOptions.shouldExternalize`, `ResolvePluginOptions.ssrConfig` + - 以下未使用的属性现已移除：`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) - - These properties were deprecated from the beginning. It is now removed. + - 这些属性从一开始就被标记为弃用，现已移除。 - [[#19987] refactor!: remove deprecated `HotBroadcaster` related types](https://github.com/vitejs/vite/pull/19987) - - These types were introduced as part of the now-deprecated Runtime API. It is now removed: `HMRBroadcaster`, `HMRBroadcasterClient`, `ServerHMRChannel`, `HMRChannel` + - 这些类型是作为现已弃用的 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__` is now required for the module runner runtime context. + - `__vite_ssr_exportName__` 现在是模块运行时上下文中的必需字段。 - [[#20045] fix: treat all `optimizeDeps.entries` values as globs](https://github.com/vitejs/vite/pull/20045) - - `optimizeDeps.entries` now does not receive literal string paths. Instead, it always receives globs. + - `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) - - Some middlewares are now applied before the `configureServer` / `configurePreviewServer` hook. Note that if you don't expect a certain route to apply the [`server.cors`](../config/server-options.md#server-cors) / [`preview.cors`](../config/preview-options.md#preview-cors) option, make sure to remove the related headers from the response. + - 某些中间件现在会在 `configureServer` / `configurePreviewServer` 钩子之前被应用。请注意，如果你不希望某个路由应用 [`server.cors`](../config/server-options.md#server-cors) / [`preview.cors`](../config/preview-options.md#preview-cors) 配置，请务必从响应中移除相关的请求头。 -## Migration from v5 +## 从 v5 迁移 {#migration-from-v5} -Check the [Migration from v5 Guide](https://v6.vite.dev/guide/migration.html) in the Vite v6 docs first to see the needed changes to port your app to Vite 6, and then proceed with the changes on this page. ->>>>>>> d63725c8b820429543943d4f97810e4cb0299aa0 +请先查阅 Vite v6 文档中的 [从 v5 迁移指南](https://v6.vite.dev/guide/migration.html)，了解将你的应用迁移到 Vite 6 所需的变更，然后再继续执行本页中的相关更改。 From efeb507c4a506af5fca5d480d507abf48421d61e Mon Sep 17 00:00:00 2001 From: Kylin <75473409+lxKylin@users.noreply.github.com> Date: Fri, 20 Jun 2025 10:16:02 +0800 Subject: [PATCH 4/4] Update guide/migration.md Co-authored-by: thinkasany <480968828@qq.com> --- guide/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/migration.md b/guide/migration.md index 1ea691b7..63b4732f 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -4,7 +4,7 @@ Vite 不再支持已结束生命周期（EOL）的 Node.js 18。现在需要使用 Node.js 20.19+ 或 22.12+。 -## 默认浏览器目标变更 {#-default-browser-target-change} +## 默认浏览器目标变更 {#default-browser-target-change} `build.target` 的默认浏览器目标已更新为更新的浏览器版本。