Merge pull request #1176 from vitejs/sync-ebd74c77-1

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

Author: waynzh

.vitepress/config.ts

@@ -307,19 +307,28 @@ export default defineConfig({
     sidebar: {
       '/guide/': [
         {
-          text: '指引',
+          text: '介绍',
           items: [
             {
-              text: '为什么选 Vite',
-              link: '/guide/why'
+              text: '开始',
+              link: '/guide/',
             },
             {
-              text: '开始',
-              link: '/guide/'
+              text: '理念',
+              link: '/guide/philosophy',
             },
+            {
+              text: '为什么选 Vite',
+              link: '/guide/why',
+            },
+          ],
+        },
+        {
+          text: '指引',
+          items: [
             {
               text: '功能',
-              link: '/guide/features'
+              link: '/guide/features',
             },
             {
               text: '命令行接口',
@@ -357,22 +366,14 @@ export default defineConfig({
               text: '后端集成',
               link: '/guide/backend-integration'
             },
-            {
-              text: '比较',
-              link: '/guide/comparisons'
-            },
             {
               text: '故障排除',
-              link: '/guide/troubleshooting'
+              link: '/guide/troubleshooting',
             },
             {
               text: '性能',
               link: '/guide/performance',
             },
-            {
-              text: '理念',
-              link: '/guide/philosophy',
-            },
             {
               text: '从 v5 迁移',
               link: '/guide/migration'

.vitepress/theme/components/landing/1. hero-section/HeroDiagram.vue

@@ -520,7 +520,8 @@ onMounted(() => {
     bottom: 0;
     transform: translate3d(0, 0, 0) scale(1);
     transition: transform 0.3s ease-in-out;
-    background: linear-gradient(
+    background:
+      linear-gradient(
         130deg,
         rgba(61, 61, 61, 0.3) 0%,
         rgba(61, 61, 61, 0) 40%
@@ -713,7 +714,8 @@ onMounted(() => {
     opacity: 0.1;
   }
 
-  background: url('/noise.png'),
+  background:
+    url('/noise.png'),
     radial-gradient(
       circle at right center,
       rgb(86, 50, 119) 0%,
@@ -729,7 +731,8 @@ onMounted(() => {
   );
 
   @media (min-width: 1024px) {
-    background: url('/noise.png'),
+    background:
+      url('/noise.png'),
       radial-gradient(
         circle at right center,
         rgba(75, 41, 105, 0.5) 0%,
@@ -747,7 +750,8 @@ onMounted(() => {
   }
 
   @media (min-width: 1500px) {
-    background: url('/noise.png'),
+    background:
+      url('/noise.png'),
       radial-gradient(
         circle at right center,
         rgba(75, 41, 105, 0.5) 0%,
@@ -765,7 +769,8 @@ onMounted(() => {
   }
 
   @media (min-width: 1800px) {
-    background: url('/noise.png'),
+    background:
+      url('/noise.png'),
       radial-gradient(
         circle at right center,
         rgba(75, 41, 105, 0.5) 0%,

.vitepress/theme/components/landing/2. feature-section/FeatureInstantServerStart.vue

@@ -342,7 +342,8 @@ onUnmounted(() => {
       bottom: 0;
       height: 100%;
       border-radius: 12px 0 0 12px;
-      background: url('/noise.png'),
+      background:
+        url('/noise.png'),
         radial-gradient(
           ellipse 140% 80% at 96% bottom,
           #13b351 0%,

.vitepress/theme/composables/sponsor.ts

@@ -45,12 +45,6 @@ const viteSponsors: Pick<Sponsors, 'special' | 'gold'> = {
       url: 'https://nuxtlabs.com',
       img: '/nuxtlabs.svg',
     },
-    // sponsors bluwy
-    {
-      name: 'Astro',
-      url: 'https://astro.build',
-      img: '/astro.svg',
-    },
   ],
   gold: [
     // now automated via sponsors.vuejs.org too

.vitepress/theme/styles/landing.css

@@ -176,7 +176,8 @@ html:has(.landing) {
 
     &.btn--primary {
       position: relative;
-      background: radial-gradient(
+      background:
+        radial-gradient(
           141.42% 141.42% at 100% 0%,
           rgba(255, 255, 255, 0.4) 0%,
           rgba(255, 255, 255, 0) 100%
@@ -194,7 +195,8 @@ html:has(.landing) {
       box-shadow: 0 1px 0 0 rgba(255, 255, 255, 0.75) inset;
 
       &:hover {
-        background: radial-gradient(
+        background:
+          radial-gradient(
             141.42% 141.42% at 100% 0%,
             rgba(255, 255, 255, 0.5) 0%,
             rgba(255, 255, 255, 0) 100%

_data/team.js

@@ -45,7 +45,7 @@ export const core = [
     avatar: 'https://github.com/bluwy.png',
     name: 'Bjorn Lu',
     title: 'Open Source Developer',
-    desc: 'Vite, Astro, and Svelte core team member.',
+    desc: 'Building tools for fun.',
     links: [
       { icon: 'github', link: 'https://github.com/bluwy' },
       { icon: 'bluesky', link: 'https://bsky.app/profile/bluwy.me' },

blog/announcing-vite2.md

@@ -33,7 +33,7 @@ Vite（法语意思是 “快”，发音为 `/vit/`，类似 veet）是一种
 
 想知道 Vite 有多快？看看这个[视频比较](https://twitter.com/amasad/status/1355379680275128321)， 在 Repl.it 上从零启动一个基于 Vite 的 React 应用，浏览器页面加载完毕的时候，基于 CRA（`create-react-app`）的应用甚至还没有安装完依赖。
 
-如果你还没听说过 Vite 到底是什么，可以到 [这里](/guide/why) 了解一下项目的设计初衷。如果你想要了解 Vite 跟其它一些类似的工具有什么区别，可以参考这里的 [对比](/guide/comparisons)。
+如果你还没听说过 Vite 到底是什么，可以到 [这里](/guide/why) 了解一下项目的设计初衷。如果你想要了解 Vite 跟其它一些类似的工具有什么区别，可以参考这里的 [对比](https://v5.vite.dev/guide/comparisons.html)。
 
 ## 2.0 带来了什么 {#whats-new-in-2-0}
 

guide/features.md

@@ -71,18 +71,12 @@ export type { T }
 
 - [TypeScript 文档](https://www.typescriptlang.org/tsconfig#useDefineForClassFields)
 
-从 Vite v2.5.0 开始，如果 TypeScript 的 target 是 `ESNext` 或 `ES2022` 及更新版本，此选项默认值则为 `true`。这与 [`tsc` v4.3.2 及以后版本的行为](https://github.com/microsoft/TypeScript/pull/42663) 一致。这也是标准的 ECMAScript 的运行时行为。
+如果 TypeScript 的 target 是 `ES2022` 或更高版本，包括 `ESNext`，那么默认值将为 `true`。这与 [TypeScript 4.3.2 及以后版本的行为](https://github.com/microsoft/TypeScript/pull/42663) 保持一致。
 
 若设了其他 TypeScript target，则本项会默认为 `false`.
 
-但对于那些习惯其他编程语言或旧版本 TypeScript 的开发者来说，这可能是违反直觉的。
-你可以参阅 [TypeScript 3.7 发布日志](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) 中了解更多关于如何兼容的信息。
-
 如果你正在使用一个严重依赖 class fields 的库，请注意该库对此选项的预期设置。
-
-大多数库都希望 `"useDefineForClassFields": true`，如 [MobX](https://mobx.js.org/installation.html#use-spec-compliant-transpilation-for-class-properties)。
-
-但是有几个库还没有兼容这个新的默认值，其中包括 [`lit-element`](https://github.com/lit/lit-element/issues/1030)。如果遇到这种情况，请将 `useDefineForClassFields` 设置为 `false`。
+虽然大多数库期望 `"useDefineForClassFields": true`，但如果你的库不支持它，你可以明确地将 `useDefineForClassFields` 设置为 `false`。
 
 #### `target` {#target}
 
@@ -124,20 +118,26 @@ Vite 默认的类型定义是写给它的 Node.js API 的。要将其补充到
 /// <reference types="vite/client" />
 ```
 
+::: details 使用 `compilerOptions.types`
+
 或者，你也可以将 `vite/client` 添加到 `tsconfig.json` 中的 `compilerOptions.types` 下：
 
 ```json [tsconfig.json]
 {
   "compilerOptions": {
-    "types": ["vite/client"]
+    "types": ["vite/client", "some-other-global-lib"]
   }
 }
 ```
 
-这将会提供以下类型定义补充：
+需要注意的是，如果指定了 [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig#types)，则只有这些包会被包含在全局作用域内（而不是所有的“@types”包）。
+
+:::
+
+`vite/client` 会提供以下类型定义补充：
 
 - 资源导入 (例如：导入一个 `.svg` 文件)
-- `import.meta.env` 上 Vite 注入的 [常量变量](./env-and-mode#env-variables) 的类型定义
+- `import.meta.env` 上 Vite 注入的 [常量](./env-and-mode#env-variables) 的类型定义
 - `import.meta.hot` 上的 [HMR API](./api-hmr) 类型定义
 
 ::: tip
@@ -204,22 +204,24 @@ HTML 文件位于 Vite 项目的[最前端和中心](/guide/#index-html-and-proj
 
 要退出对某些元素的 HTML 处理，可以在元素上添加 `vite-ignore` 属性，这在引用外部 assets 或 CDN 时非常有用。
 
-## Vue {#vue}
+## 框架支持 {#frameworks}
+
+所有现代框架都已和 Vite 集成。大多数框架插件由各自的框架团队维护，唯有官方的 Vue 和 React Vite 插件由 Vite 组织维护。
 
-Vite 为 Vue 提供第一优先级支持：
+- Vue 支持：[@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)
+- Vue JSX 支持：[@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx)
+- React 支持：[@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react)
+- React 使用 SWC 的支持：[@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc)
 
-- Vue 3 单文件组件支持：[@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)
-- Vue 3 JSX 支持：[@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx)
-- Vue 2.7 SFC 支持：[@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2)
-- Vue 2.7 JSX 支持：[@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx)
+查看 [插件指南](/plugins/) 了解更多信息。
 
 ## JSX {#jsx}
 
 `.jsx` 和 `.tsx` 文件同样开箱即用。JSX 的转译同样是通过 [esbuild](https://esbuild.github.io)。
 
-Vue 用户应使用官方提供的 [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) 插件，它提供了 Vue 3 特性的支持，包括 HMR，全局组件解析，指令和插槽。
+你选择的框架已经可以开箱即用地配置 JSX（例如，Vue 用户应使用官方的 [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) 插件，它提供了 Vue 3 特定的功能，包括 HMR，全局组件解析，指令和插槽）。
 
-如果不是在 React 或 Vue 中使用 JSX，自定义的 `jsxFactory` 和 `jsxFragment` 可以使用 [`esbuild` 选项](/config/shared-options.md#esbuild) 进行配置。例如对 Preact：
+如果你使用自己的框架运行 JSX，可以使用 [`esbuild` 选项](/config/shared-options.md#esbuild) 来配置自定义的 `jsxFactory` 和 `jsxFragment`。例如，Preact 插件会使用：
 
 ```js twoslash [vite.config.js]
 import { defineConfig } from 'vite'

guide/index.md

@@ -202,7 +202,31 @@ Vite 也支持多个 `.html` 作入口点的 [多页面应用模式](./build#mul
 
 ## 使用未发布的功能 {#using-unreleased-commits}
 
-如果你迫不及待想要体验最新的功能，可以自行克隆 [vite 仓库](https://github.com/vitejs/vite) 到本地机器上然后自行将其链接（将需要 [pnpm](https://pnpm.io/)）：
+如果你迫不及待想要体验最新的功能，可以使用 https://pkg.pr.new 安装特定的 Vite 提交：
+
+::: code-group
+
+```bash [npm]
+$ npm install -D https://pkg.pr.new/vite@SHA
+```
+
+```bash [Yarn]
+$ yarn add -D https://pkg.pr.new/vite@SHA
+```
+
+```bash [pnpm]
+$ pnpm add -D https://pkg.pr.new/vite@SHA
+```
+
+```bash [Bun]
+$ bun add -D https://pkg.pr.new/vite@SHA
+```
+
+:::
+
+将 `SHA` 替换为 [Vite 的提交 SHA](https://github.com/vitejs/vite/commits/main/)。请注意，仅最近一个月的提交有效，旧版本提交的构建产物会被清除。
+
+或者，你可以克隆 [Vite 代码仓库](https://github.com/vitejs/vite) 到本地，自行构建并建立软链接（需安装 [pnpm](https://pnpm.io/)）：
 
 ```bash
 git clone https://github.com/vitejs/vite.git
@@ -215,6 +239,10 @@ pnpm link --global # 在这一步中可使用你喜欢的包管理器
 
 然后，回到你的 Vite 项目并运行 `pnpm link --global vite`（或者使用你的其他包管理工具来全局链接 `vite`）。重新启动开发服务器来体验新功能吧！
 
+::: tip 处理依赖中的 Vite 版本
+若需替换依赖链中传递使用的 Vite 版本（Transitive Dependencies），应使用 [npm overrides](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#overrides) 或 [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides)。
+:::
+
 ## 社区 {#community}
 
 如果你有疑问或者需要帮助，可以到 [Discord](https://chat.vite.dev) 和 [GitHub Discussions](https://github.com/vitejs/vite/discussions) 社区来寻求帮助。

guide/why.md

@@ -57,6 +57,10 @@ 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 与 X 的区别是？ {#how-is-vite-different-from-x}
+## Vite 与其他免打包构建工具的关系是什么？{##how-vite-relates-to-other-unbundled-build-tools}
 
-你可以查看 [比较](./comparisons.md) 章节获取更多细节，了解 Vite 与同类工具的异同。
+Preact 团队的 [WMR](https://github.com/preactjs/wmr) 旨在提供类似的功能集。Vite 用于开发和构建的通用 Rollup 插件 API 就是受其启发。WMR 已经不再维护。Preact 团队现在推荐使用 Vite 和 [@preactjs/preset-vite](https://github.com/preactjs/preset-vite)。
+
+[Snowpack](https://www.snowpack.dev/) 也是一个免打包的原生 ESM 开发服务器，与 Vite 的职责非常相似。Vite 的依赖预打包也受到了 Snowpack v1（现在是 [`esinstall`](https://github.com/snowpackjs/snowpack/tree/main/esinstall)）的启发。Snowpack 已经不再维护。Snowpack 团队现在正在研究由 Vite 驱动的静态网站构建器 [Astro](https://astro.build/)。
+
+[@web/dev-server](https://modern-web.dev/docs/dev-server/overview/)（以前是 `es-dev-server`）是一个伟大的项目，Vite 1.0 的基于 Koa 的服务器设置就是受其启发。`@web` 这个项目正在积极维护，并包含许多其他优秀的工具，这些工具也可能对 Vite 用户有所帮助。