web-tooling-vite

Vite 模式

快速指南： Vite 在开发环境中以未打包的 ES 模块提供服务，在生产环境中则会进行打包，因此大多数配置决策只适用于其中一个阶段。API 取决于版本：Vite 8 使用 Rolldown 打包（build.rolldownOptions、codeSplitting.groups、resolve.tsconfigPaths），Vite 7 使用 Rollup（build.rollupOptions、manualChunks，并手动将别名同步到 tsconfig.json）。从 Vite 6 开始，Sass 使用现代 API；Vite 7 已移除旧版 API。

详细资源：

• examples/core.md — 别名、代码块拆分、特定环境的构建、模块预加载、Sass、Environment API 和开发代理的完整配置
• reference.md — 开发／生产设置、构建目标表、各版本说明和 Vite 8 迁移清单

---

适用路径

编写配置前，先查看 package.json 中的 vite 版本；两个分支使用相同的名称，但行为不同。

• Vite 8（Rolldown） — 使用 build.rolldownOptions、通过 codeSplitting.groups 拆分代码块，并使用 resolve.tsconfigPaths，而不是手动同步别名。build.rollupOptions 仍可作为已弃用的别名解析，这也是错误版本的配置看起来能正常工作的原因。
• Vite 7（Rollup） — 使用 build.rollupOptions 和 manualChunks，并在 vite.config.ts 和 tsconfig.json 中同时声明别名。

---

<critical_requirements>

编写 Vite 配置前

按版本在一个地方声明路径别名 — Vite 8 使用 resolve.tsconfigPaths；Vite 7 则要在 vite.config.ts 和 tsconfig.json 中声明相同的一组别名。如果两处配置不一致，别名可能只在一个工具中解析成功，导致构建工具和编辑器对同一导入产生不同判断。

根据版本匹配打包器选项。 Vite 8 使用 build.rolldownOptions 和 codeSplitting.groups；此版本已移除对象形式的 manualChunks，使用它不会报错，但也不会进行分组。

按模式拆分配置，而不是只提供一种构建。 使用 defineConfig(({ mode }) => …) 和 loadEnv，避免在开发环境中启用压缩，也避免将源码映射包含在生产包中。

优先使用 build.modulePreload.polyfill，这是当前的写法 — build.polyfillModulePreload 已弃用，也无法控制要预加载哪些依赖。

</critical_requirements>

---

自动检测： Vite、vite.config.ts、vite.config.js、defineConfig、loadEnv、manualChunks、advancedChunks、codeSplitting.groups、rolldownOptions、rollupOptions、modulePreload、resolve.alias、resolve.tsconfigPaths、build.target、baseline-widely-available、VITE_

适用于：

• 为前端应用配置 Vite 构建
• 配置路径别名，并确保打包器和类型检查器都能解析这些别名
• 为可缓存的生产输出拆分供应商代码块
• 使用 loadEnv 和 define 配置各模式的构建（开发、预发布、生产）
• 将配置从 Vite 7 迁移到 Vite 8
• 模块预加载、构建目标和 Sass 预处理

其他地方处理：

• 除别名所需的 paths 条目外的编译器选项和类型检查行为
• Lint 和格式化配置
• 在浏览器中运行的应用代码 — 这里只涉及构建时配置
• 由 SSR 元框架负责的构建编排；此类框架有自己的配置文件
• 构建命令相关的流水线和部署事项

---

开发和生产使用不同的机制。开发服务器按需转换模块，并以未打包的形式提供，因此不会进行摇树优化、压缩或代码块拆分；生产构建则会由打包器执行这三项操作。所有未能在发布前发现的缺陷都藏在两者的差异中 — 被摇树优化移除的样式表、只在生产环境中存在的代码块，或仅在本地环境中设置的环境变量。

因此，针对任何选项，值得思考的问题是：它作用于哪个阶段，另一个阶段是否会用到它。

---

<decision_framework>

分块拆分

Vite 8 (Rolldown)?
├─ Separating vendors by package → codeSplitting.groups with a test regex ✓
└─ Constraining by size or share count → codeSplitting maxSize / minSize / minShareCount

Vite 7 (Rollup)?
├─ Separating vendors by package → manualChunks, object form ✓
└─ Logic per module id → manualChunks, function form

advancedChunks 是同一功能在 rolldown-vite 中的名称；在 Vite 8 中改名为 codeSplitting。

构建目标

Are there browsers below the default floor to support?
├─ YES → @vitejs/plugin-legacy alongside the modern build
└─ NO  → Smallest possible output?
    ├─ YES → 'esnext'
    └─ NO  → 'baseline-widely-available' (the default) ✓, or an explicit list
              such as ['chrome111', 'safari16.4'] when a contract names versions

</decision_framework>

---

核心模式

模式 1：路径别名

一组别名，同时可由打包器和类型检查器解析。

// Vite 8 — read straight from tsconfig.json
resolve: { tsconfigPaths: true },

// Vite 7 — declared here and mirrored in tsconfig.json "paths"
resolve: {
  alias: { "@": path.resolve(__dirname, "./src") },
},

resolve.tsconfigPaths 默认关闭，因为通过 tsconfig 解析会增加启动时间；仅在项目使用 paths 时启用。它只涵盖 tsconfig.json 中声明的内容，因此，没有 paths 条目的别名——例如项目外的包，或构建时替换的存根——仍需在旁边配置 resolve.alias。

完整代码：examples/core.md

---

模式 2：拆分供应商代码块

依赖项的更新节奏比应用代码慢，因此单独的代码块可以在多次部署之间留存在浏览器缓存中。

// Vite 8
build: {
  rolldownOptions: {
    output: {
      codeSplitting: {
        groups: [{ name: "vendor", test: /[\\/]node_modules[\\/]/ }],
      },
    },
  },
},

对于更新节奏不同的依赖组，应分别缩小 test 的匹配范围；如果所有内容都放在一个代码块中，任何升级都会导致该代码块失效。

完整代码，包括 Vite 7 的写法：examples/core.md

---

模式 3：按模式构建

defineConfig 接受函数，因此配置可以根据 --mode 而有所不同。

export default defineConfig(({ mode }) => ({
  build: {
    sourcemap: mode !== "production",
    minify: mode === "production",
  },
}));

.env 文件的选择取决于 --mode，而不是 NODE_ENV。loadEnv(mode, cwd, "") 会返回所有变量，包括没有客户端前缀的变量，因此应将其结果视为服务端值，而不是传给 define 的内容。

完整代码：examples/core.md

---

模式 4：模块预加载

build: {
  modulePreload: {
    polyfill: false,
    resolveDependencies: (filename, deps) =>
      deps.filter((dep) => !dep.includes("rarely-used-vendor")),
  },
},

只有当目标环境支持原生模块预加载时，移除 polyfill 才是安全的；可以通过 resolveDependencies 将大型代码块排除在初始预加载列表之外。

完整代码：examples/core.md

---

模式 5：Sass

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@use "./src/styles/variables" as *;`,
    },
  },
},

从 Vite 6 开始，现代 API 是默认选项；从 Vite 7 开始，它是唯一选项，因此，仍传入 api: "legacy" 的配置会报错，而不会回退。迁移意味着将 @import 改为 @use/@forward，并使用命名空间访问。

---

模式 6：开发服务器代理

server: {
  proxy: {
    "/api": { target: "http://localhost:8000", changeOrigin: true },
  },
},

代理可让开发环境保持同源，因此，对于生产环境中本就会同源的后端，无需配置 CORS。

---

模式 7：环境 API

面向框架作者和多运行时构建；截至 Vite 8，该功能仍处于 RC 阶段，普通的单客户端应用无需使用。

environments: {
  client: { build: { outDir: "dist/client" } },
  ssr: { build: { outDir: "dist/server", ssr: true } },
},

完整代码：examples/core.md

---

<red_flags>

风险提示

运行时会出问题：

• 在 Vite 8 中使用对象形式的 manualChunks——该功能已移除，因此分组会静默失效，预期的供应商代码块也不会出现在 dist 中
• 使用已在 Vite 7 中移除的 splitVendorChunkPlugin——导入会在构建开始前抛出错误
• 使用已在 Vite 7 中移除的 target: 'modules'——它已被 'baseline-widely-available' 替代
• 在 Vite 7 或更高版本中使用 Sass api: "legacy"——旧版 API 已移除，而非弃用
• vite.config.ts 中存在别名，但 tsconfig.json 中没有，或反之——构建成功但类型检查失败，或者编辑器能解析某个导入，而打包器无法解析

容易令人意外的行为：

• 在 Vite 8 中，build.rollupOptions 仍可作为弃用别名解析，因此 Vite 7 配置看似可用，直到需要使用仅限 Rolldown 的选项
• resolve.tsconfigPaths 默认关闭；启用它是一个有意为之的步骤，而不是回退方案
• Rolldown 会在代码拆分组旁额外生成一个 runtime.js 代码块
• loadEnv(mode, cwd, "") 会加载文件中的所有变量，无论是否有前缀——通过 define 内联其中任何变量，都会将其发布到构建产物中
• 在 Vite 8 中，build.commonjsOptions 不起作用，因为 Rolldown 原生处理 CommonJS
• 在 Vite 8 中，esbuild 选项会自动转换为 oxc，并静默丢弃 Oxc 没有对应项的选项
• 如果生产环境仍启用 sourcemap，随包发布的源码将可读；'hidden' 会保留 sourcemap 供错误报告使用，但不会从包中链接到它们

</red_flags>