release: v5.3.1

Author: waynzh

.vitepress/buildEnd.config.ts

@@ -1,12 +1,13 @@
-import path from 'path'
-import { writeFileSync } from 'fs'
+import path from 'node:path'
+import { writeFileSync } from 'node:fs'
 import { Feed } from 'feed'
-import { createContentLoader, type SiteConfig } from 'vitepress'
+import type { SiteConfig } from 'vitepress'
+import { createContentLoader } from 'vitepress'
 
 const siteUrl = 'https://vitejs.dev'
 const blogUrl = `${siteUrl}/blog`
 
-export const buildEnd = async (config: SiteConfig) => {
+export const buildEnd = async (config: SiteConfig): Promise<void> => {
   const feed = new Feed({
     title: 'Vite',
     description: 'Next Generation Frontend Tooling',

.vitepress/config.ts

@@ -1,4 +1,5 @@
-import { defineConfig, DefaultTheme } from 'vitepress'
+import type { DefaultTheme } from 'vitepress'
+import { defineConfig } from 'vitepress'
 import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { buildEnd } from './buildEnd.config'
 
@@ -79,6 +80,7 @@ export default defineConfig({
     ['meta', { property: 'og:image', content: ogImage }],
     ['meta', { property: 'og:url', content: ogUrl }],
     ['meta', { property: 'og:description', content: ogDescription }],
+    ['meta', { property: 'og:site_name', content: 'vitejs' }],
     ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
     ['meta', { name: 'twitter:site', content: '@vite_js' }],
     ['meta', { name: 'theme-color', content: '#646cff' }],
@@ -396,10 +398,10 @@ export default defineConfig({
       .replace(/\/index\.md$/, '/')
       .replace(/\.md$/, '/')
     pageData.frontmatter.head ??= []
-    pageData.frontmatter.head.unshift([
-      'link',
-      { rel: 'canonical', href: canonicalUrl },
-    ])
+    pageData.frontmatter.head.unshift(
+      ['link', { rel: 'canonical', href: canonicalUrl }],
+      ['meta', { property: 'og:title', content: pageData.title }],
+    )
     return pageData
   },
   markdown: {

.vitepress/theme/composables/sponsor.ts

@@ -1,4 +1,4 @@
-import { ref, onMounted, onUnmounted } from 'vue'
+import { onMounted, onUnmounted, ref } from 'vue'
 
 interface Sponsors {
   special: Sponsor[]
@@ -64,6 +64,16 @@ const viteSponsors: Pick<Sponsors, 'special' | 'gold'> = {
       img: '/transloadit.svg',
       hasDark: true,
     },
+    {
+      name: 'Huly',
+      url: 'https://huly.io/',
+      img: '/huly.svg',
+    },
+    {
+      name: 'Handsontable',
+      url: 'https://handsontable.com/docs/react-data-grid/?utm_source=vite_docs&utm_medium=sponsorship&utm_campaign=library_sponsorship_2024',
+      img: '/handsontable.svg',
+    },
   ],
 }
 

blog/announcing-vite3.md

@@ -29,7 +29,7 @@ head:
 
 _July 23, 2022_ - Check out the [Vite 4.0 announcement](./announcing-vite4.md)
 
-In February last year, [Evan You](https://twitter.com/youyuxi) released Vite 2. Since then, its adoption has grown non-stop, reaching more than 1 million npm downloads per week. A sprawling ecosystem rapidly formed after the release. Vite is powering a renewed innovation race in Web frameworks. [Nuxt 3](https://v3.nuxtjs.org/) uses Vite by default. [SvelteKit](https://kit.svelte.dev/), [Astro](https://astro.build/), [Hydrogen](https://hydrogen.shopify.dev/), and [SolidStart](https://docs.solidjs.com/start) are all built with Vite. [Laravel has now decided to use Vite by default](https://laravel.com/docs/9.x/vite). [Vite Ruby](https://vite-ruby.netlify.app/) shows how Vite can improve Rails DX. [Vitest](https://vitest.dev) is making strides as a Vite-native alternative to Jest. Vite is behind [Cypress](https://docs.cypress.io/guides/component-testing/writing-your-first-component-test) and [Playwright](https://playwright.dev/docs/test-components)'s new Component Testing features, Storybook has [Vite as an official builder](https://github.com/storybookjs/builder-vite). And [the list goes on](https://patak.dev/vite/ecosystem.html). Maintainers from most of these projects got involved in improving the Vite core itself, working closely with the Vite [team](https://vitejs.dev/team) and other contributors.
+In February last year, [Evan You](https://twitter.com/youyuxi) released Vite 2. Since then, its adoption has grown non-stop, reaching more than 1 million npm downloads per week. A sprawling ecosystem rapidly formed after the release. Vite is powering a renewed innovation race in Web frameworks. [Nuxt 3](https://v3.nuxtjs.org/) uses Vite by default. [SvelteKit](https://kit.svelte.dev/), [Astro](https://astro.build/), [Hydrogen](https://hydrogen.shopify.dev/), and [SolidStart](https://docs.solidjs.com/quick-start) are all built with Vite. [Laravel has now decided to use Vite by default](https://laravel.com/docs/9.x/vite). [Vite Ruby](https://vite-ruby.netlify.app/) shows how Vite can improve Rails DX. [Vitest](https://vitest.dev) is making strides as a Vite-native alternative to Jest. Vite is behind [Cypress](https://docs.cypress.io/guides/component-testing/writing-your-first-component-test) and [Playwright](https://playwright.dev/docs/test-components)'s new Component Testing features, Storybook has [Vite as an official builder](https://github.com/storybookjs/builder-vite). And [the list goes on](https://patak.dev/vite/ecosystem.html). Maintainers from most of these projects got involved in improving the Vite core itself, working closely with the Vite [team](https://vitejs.dev/team) and other contributors.
 
 ![Vite 3 Announcement Cover Image](/og-image-announcing-vite3.png)
 

blog/announcing-vite5-1.md

@@ -66,7 +66,7 @@ Import CSS files as URLs now works reliably and correctly. This was the last rem
 
 ### `build.assetsInlineLimit` now supports a callback
 
-Users can now [provide a callback](/config/build-options.html#build-assetsinlinelimit) that returns a boolean to opt-in or opt-out of inlining for specific assets. If `undefined` is returned, the defalt logic applies. See ([#15366](https://github.com/vitejs/vite/issues/15366)).
+Users can now [provide a callback](/config/build-options.html#build-assetsinlinelimit) that returns a boolean to opt-in or opt-out of inlining for specific assets. If `undefined` is returned, the default logic applies. See ([#15366](https://github.com/vitejs/vite/issues/15366)).
 
 ### Improved HMR for circular import
 
@@ -82,7 +82,7 @@ The preview server now exposes a `close` method, which will properly teardown th
 
 ## Performance improvements
 
-Vite keeps getting faster with each release, and Vite 5.1 is packed with performance improvements. We measured the loading time for 10K modules (25 level deep tree) using [vite-dev-server-perf](https://github.com/yyx990803/vite-dev-server-perf) for all minor versions from Vite 4.0. This is a good benchmark to meassure the effect of Vite's bundle-less approach. Each module is a small TypeScript file with a counter and imports to other files in the tree, so this mostly meassuring the time it takes to do the requests a separate modules. In Vite 4.0, loading 10K modules took 8 seconds on a M1 MAX. We had a breakthrough in [Vite 4.3 were we focused on performance](./announcing-vite4-3.md), and we were able to load them in 6.35 seconds. In Vite 5.1, we managed to do another performance leap. Vite is now serving the 10K modules in 5.35 seconds.
+Vite keeps getting faster with each release, and Vite 5.1 is packed with performance improvements. We measured the loading time for 10K modules (25 level deep tree) using [vite-dev-server-perf](https://github.com/yyx990803/vite-dev-server-perf) for all minor versions from Vite 4.0. This is a good benchmark to measure the effect of Vite's bundle-less approach. Each module is a small TypeScript file with a counter and imports to other files in the tree, so this mostly measuring the time it takes to do the requests a separate modules. In Vite 4.0, loading 10K modules took 8 seconds on a M1 MAX. We had a breakthrough in [Vite 4.3 were we focused on performance](./announcing-vite4-3.md), and we were able to load them in 6.35 seconds. In Vite 5.1, we managed to do another performance leap. Vite is now serving the 10K modules in 5.35 seconds.
 
 ![Vite 10K Modules Loading time progression](/vite5-1-10K-modules-loading-time.png)
 
@@ -113,7 +113,7 @@ The dev server had several incremental performance gains. A new middleware to sh
 
 ## Deprecations
 
-We continue to reduce Vite's API surface where possible to make the project manintainable long term.
+We continue to reduce Vite's API surface where possible to make the project maintainable long term.
 
 ### Deprecated `as` option in `import.meta.glob`
 
@@ -129,4 +129,4 @@ We are grateful to the [900 contributors to Vite Core](https://github.com/vitejs
 
 ## Acknowledgments
 
-Vite 5.1 is possible thanks to our community of contributors, maintainers in the ecosystem, and the [Vite Team](/team). A shoutout the individuals and companies sponsoring Vite development. [StackBlitz](https://stackblitz.com/), [Nuxt Labs](https://nuxtlabs.com/), and [Astro](https://astro.build) for hiring Vite team members. And also to the sponsors on [Vite's GitHub Sponsors](https://github.com/sponsors/vitejs), [Vite's Open Collective](https://opencollective.com/vite), and [Evan You's GitHub Sponsors](https://github.com/sponsors/yyx990803).
+Vite 5.1 is possible thanks to our community of contributors, maintainers in the ecosystem, and the [Vite Team](/team). A shout out to the individuals and companies sponsoring Vite development. [StackBlitz](https://stackblitz.com/), [Nuxt Labs](https://nuxtlabs.com/), and [Astro](https://astro.build) for hiring Vite team members. And also to the sponsors on [Vite's GitHub Sponsors](https://github.com/sponsors/vitejs), [Vite's Open Collective](https://opencollective.com/vite), and [Evan You's GitHub Sponsors](https://github.com/sponsors/yyx990803).

config/build-options.md

@@ -48,10 +48,10 @@ type ResolveModulePreloadDependenciesFn = (
 
 `resolveDependencies` 函数将为每个动态导入调用，同时带着一个它所依赖的 chunk 列表。并且它还会为每个在入口 HTML 文件中导入的 chunk 调用。 可以返回一个新的依赖关系数组，可能被过滤后变少了，也可能有更多依赖注入进来了，同时它们的路径也被修改过。`deps` 路径是相对于 `build.outDir` 的。若在注入该模块到 HTML head 时使用 `new URL(dep, import.meta.url)` 获取绝对路径，则对于 `hostType === 'js'`，允许返回一个相对于 `hostId` 的路径。
 
-<!-- prettier-ignore-start -->
 ```js twoslash
 /** @type {import('vite').UserConfig} */
 const config = {
+  // prettier-ignore
   build: {
 // ---cut-before---
 modulePreload: {
@@ -63,7 +63,6 @@ modulePreload: {
   },
 }
 ```
-<!-- prettier-ignore-end -->
 
 解析得到的依赖路径可以再在之后使用 [`experimental.renderBuiltUrl`](../guide/build.md#advanced-base-options) 更改。
 

config/server-options.md

@@ -90,7 +90,7 @@ export default defineConfig({
 
 请注意，如果使用了非相对的 [基础路径 `base`](/config/shared-options.md#base)，则必须在每个 key 值前加上该 `base`。
 
-继承自 [`http-proxy`](https://github.com/http-party/node-http-proxy#options)。完整选项详见 [此处](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/middlewares/proxy.ts#L13)。
+继承自 [`http-proxy`](https://github.com/http-party/node-http-proxy#options)。完整选项详见 [此处](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/middlewares/proxy.ts#L13)。需要注意的是，[与 http-proxy 不同](https://github.com/http-party/node-http-proxy/issues/1669)，`changeOrigin` 选项会同时改变 host 和 origin 头以匹配目标。
 
 在某些情况下，你可能也想要配置底层的开发服务器。（例如添加自定义的中间件到内部的 [connect](https://github.com/senchalabs/connect) 应用中）为了实现这一点，你需要编写你自己的 [插件](/guide/using-plugins.html) 并使用 [configureServer](/guide/api-plugin.html#configureserver) 函数。
 

guide/api-javascript.md

@@ -422,3 +422,30 @@ async function loadConfigFromFile(
 ```
 
 手动通过 esbuild 加载一份 Vite 配置。
+
+## `preprocessCSS`
+
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13815)
+
+**类型签名：**
+
+```ts
+async function preprocessCSS(
+  code: string,
+  filename: string,
+  config: ResolvedConfig,
+): Promise<PreprocessCSSResult>
+
+interface PreprocessCSSResult {
+  code: string
+  map?: SourceMapInput
+  modules?: Record<string, string>
+  deps?: Set<string>
+}
+```
+
+预处理 `.css`、`.scss`、`.sass`、`.less`、`.styl` 和 `.stylus` 文件，将它们转化为纯 CSS，这样就可以在浏览器中使用或者被其他工具解析了。这和 [内置的 CSS 预处理器](/guide/features#css-pre-processors) 很像，如果你使用了这个功能，则必须安装相应的预处理器。
+
+使用哪个预处理器是根据 `filename` 的扩展名来推断的。如果 `filename` 以 `.module.{ext}` 结尾，那么它就会被推断为 [CSS module](https://github.com/css-modules/css-modules)，返回的结果会包含一个 `modules` 对象，这个对象将原始的类名映射到转换后的类名。
+
+需要注意的是，预处理不会解析 `url()` 或 `image-set()` 中的 URL。

guide/api-plugin.md

@@ -427,8 +427,7 @@ Vite 插件也可以提供钩子来服务于特定的 Vite 目标。这些钩子
 
     ```js
     handleHotUpdate({ server, modules, timestamp }) {
-      // 如果需要，也可使用 `server.ws.send` 来支持 Vite <5.1 版本
-      server.hot.send({ type: 'full-reload' })
+      server.ws.send({ type: 'full-reload' })
       // 手动使模块失效
       const invalidatedModules = new Set()
       for (const mod of modules) {
@@ -447,8 +446,7 @@ Vite 插件也可以提供钩子来服务于特定的 Vite 目标。这些钩子
 
     ```js
     handleHotUpdate({ server }) {
-      // 如果需要，也可使用 `server.ws.send` 来支持 Vite <5.1 版本
-      server.hot.send({
+      server.ws.send({
         type: 'custom',
         event: 'special-update',
         data: {}
@@ -555,7 +553,7 @@ Vite 暴露了 [`@rollup/pluginutils` 的 `createFilter`](https://github.com/rol
 
 ### 服务端到客户端 {#server-to-client}
 
-在插件一侧，我们可以使用 `server.hot.send`（自 Vite 5.1 起）或 `server.ws.send` 去给所有客户端广播事件：
+在插件一侧，我们可以使用 `server.ws.send` 来向客户端广播事件：
 
 ```js
 // vite.config.js
@@ -564,9 +562,8 @@ export default defineConfig({
     {
       // ...
       configureServer(server) {
-        // 示例：等待客户端连接后再发送消息
-        server.hot.on('connection', () => {
-          server.hot.send('my:greetings', { msg: 'hello' })
+        server.ws.on('connection', () => {
+          server.ws.send('my:greetings', { msg: 'hello' })
         })
       },
     },
@@ -602,7 +599,7 @@ if (import.meta.hot) {
 }
 ```
 
-然后使用 `server.hot.on`（自 Vite 5.1 起） 或 `server.ws.on` 并在服务端监听这些事件：
+然后使用 `server.ws.on` 并在服务端监听这些事件：
 
 ```js
 // vite.config.js
@@ -611,7 +608,7 @@ export default defineConfig({
     {
       // ...
       configureServer(server) {
-        server.hot.on('my:from-client', (data, client) => {
+        server.ws.on('my:from-client', (data, client) => {
           console.log('Message from client:', data.msg) // Hey!
           // reply only to the client (if needed)
           client.send('my:ack', { msg: 'Hi! I got your message!' })

guide/build.md

@@ -236,9 +236,9 @@ dist/my-lib.umd.cjs 0.30 kB / gzip: 0.16 kB
 
 单个静态的 [基础路径](#public-base-path) 在这种场景中就不够用了。Vite 在构建时为更高级的基础路径选项提供了实验性支持，可以使用 `experimental.renderBuiltUrl`。
 
-<!-- prettier-ignore-start -->
 ```ts twoslash
 import type { UserConfig } from 'vite'
+// prettier-ignore
 const config: UserConfig = {
 // ---cut-before---
 experimental: {
@@ -253,14 +253,13 @@ experimental: {
 // ---cut-after---
 }
 ```
-<!-- prettier-ignore-end -->
 
 如果 hash 后的资源和公共文件没有被部署在一起，可以根据该函数的第二个参数 `context` 上的字段 `type` 分别定义各个资源组的选项：
 
-<!-- prettier-ignore-start -->
 ```ts twoslash
 import type { UserConfig } from 'vite'
 import path from 'node:path'
+// prettier-ignore
 const config: UserConfig = {
 // ---cut-before---
 experimental: {
@@ -277,6 +276,5 @@ experimental: {
 // ---cut-after---
 }
 ```
-<!-- prettier-ignore-end -->
 
 请注意，传递的 `filename` 是一个已解码的 URL，如果函数返回了一个 URL 字符串，那么它也应该是已解码的。当 Vite 渲染 URL 时会自动处理编码。如果返回的是一个带有 `runtime` 的对象，就需要在必要的地方自行处理编码，因为运行时的代码将会按照原样呈现。

guide/env-and-mode.md

@@ -94,7 +94,7 @@ interface ImportMeta {
 }
 ```
 
-如果你的代码依赖于浏览器环境的类型，比如 [DOM](https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts) 和 [WebWorker](https://github.com/microsoft/TypeScript/blob/main/lib/lib.webworker.d.ts)，你可以在 `tsconfig.json` 中修改 [lib](https://www.typescriptlang.org/tsconfig#lib) 字段来获取类型支持。
+如果你的代码依赖于浏览器环境的类型，比如 [DOM](https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts) 和 [WebWorker](https://github.com/microsoft/TypeScript/blob/main/src/lib/webworker.generated.d.ts)，你可以在 `tsconfig.json` 中修改 [lib](https://www.typescriptlang.org/tsconfig#lib) 字段来获取类型支持。
 
 ```json
 {

guide/features.md

@@ -211,7 +211,7 @@ export default defineConfig({
 
 Vite 通过 `postcss-import` 预配置支持了 CSS `@import` 内联，Vite 的路径别名也遵从 CSS `@import`。换句话说，所有 CSS `url()` 引用，即使导入的文件在不同的目录中，也总是自动变基，以确保正确性。
 
-Sass 和 Less 文件也支持 `@import` 别名和 URL 变基（具体请参阅 [CSS Pre-processors](#css-pre-processors)）。
+Sass 和 Less 文件也支持 `@import` 别名和 URL 变基（具体请参阅 [CSS 预处理器](#css-pre-processors)）。
 
 ### PostCSS {#postcss}
 

guide/index.md

@@ -44,7 +44,7 @@ Vite 还提供了强大的扩展性，可通过其 [插件 API](./api-plugin) 
 ## 搭建第一个 Vite 项目 {#scaffolding-your-first-vite-project}
 
 ::: tip 兼容性注意
-Vite 需要 [Node.js](https://nodejs.org/en/) 版本 18+，20+。然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。
+Vite 需要 [Node.js](https://nodejs.org/en/) 版本 18+ 或 20+。然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。
 :::
 
 ::: code-group
@@ -87,6 +87,8 @@ bun create vite my-vue-app --template vue
 
 查看 [create-vite](https://github.com/vitejs/vite/tree/main/packages/create-vite) 以获取每个模板的更多细节：`vanilla`，`vanilla-ts`, `vue`, `vue-ts`，`react`，`react-ts`，`react-swc`，`react-swc-ts`，`preact`，`preact-ts`，`lit`，`lit-ts`，`svelte`，`svelte-ts`，`solid`，`solid-ts`，`qwik`，`qwik-ts`。
 
+你可以使用 `.` 作为项目名称，在当前目录中创建项目脚手架。
+
 ## 社区模板 {#community-templates}
 
 create-vite 是一个快速生成主流框架基础模板的工具。查看 Awesome Vite 仓库的 [社区维护模板](https://github.com/vitejs/awesome-vite#templates)，里面包含各种工具和不同框架的模板。
@@ -103,6 +105,44 @@ npm install
 npm run dev
 ```
 
+## 手动安装 {#manual-installation}
+
+在你的项目中，可以用以下方法来安装 `vite` 命令行工具：
+
+::: code-group
+
+```bash [NPM]
+$ npm install -D vite
+```
+
+```bash [Yarn]
+$ yarn add -D vite
+```
+
+```bash [PNPM]
+$ pnpm add -D vite
+```
+
+```bash [Bun]
+$ bun add -D vite
+```
+
+:::
+
+并创建一个像这样的 `index.html` 文件：
+
+```html
+<p>Hello Vite!</p>
+```
+
+然后在终端中运行 `vite`：
+
+```bash
+vite
+```
+
+就可以在 `http://localhost:5173` 上访问 `index.html`。
+
 ## `index.html` 与项目根目录 {#index-html-and-project-root}
 
 你可能已经注意到，在一个 Vite 项目中，`index.html` 在项目最外层而不是在 `public` 文件夹内。这是有意而为之的：在开发期间 Vite 是一个服务器，而 `index.html` 是该 Vite 项目的入口文件。