vite-advanced

Vite 高级模式

围绕 Vite 8（由 Rolldown 驱动）的封装，而非其文档的副本。 Vite 官方文档是配置项、API 范围和迁移机制的权威来源。 本技能涵盖项目内部差异，以及四条可强制执行的规则。

Vite 8 以 Rolldown（基于 Rust 的统一打包器）取代 esbuild+Rollup 流水线， 并作为新项目的默认选项。advancedChunks 取代 manualChunks；build.rollupOptions 更名为 build.rolldownOptions。

上游文档覆盖范围（此处不重复说明）

从 Vite 文档获取以下内容，不要指望此处提供。标记了规则的行在对应规则文件中保留 了范围更窄、可强制执行的项目内部规范：查看规则文件了解项目规范立场，从文档获取完整 API。

主题	从以下位置获取
Vite 7 到 8 的迁移：rolldownOptions、transformWithOxc、moduleType: 'js'、已移除的钩子和输出格式、浏览器目标版本升级	https://vite.dev/guide/migration
采用 Rolldown 的路径、rolldown-vite、Oxc、advancedChunks 分组语法（项目内部规范子集见 rules/vite-advanced-chunks.md）	https://vite.dev/guide/rolldown
构建选项：target、minify、sourcemap、cssCodeSplit、cssMinify、assetsInlineLimit、chunkSizeWarningLimit	https://vite.dev/config/build-options
依赖预打包以及 optimizeDeps 的 include/exclude/force	https://vite.dev/guide/dep-pre-bundling
SSR：客户端和服务端入口、中间件模式开发服务、生产环境服务端接线、流式传输	https://vite.dev/guide/ssr
环境 API 配置和各环境的构建输出（项目内部规范子集见 rules/vite-environments.md）	https://vite.dev/guide/api-environment
插件的环境 API：this.environment、perEnvironmentPlugin、applyToEnvironment	https://vite.dev/guide/api-environment-plugins
框架的环境 API：createBuilder、buildApp、ModuleRunner	https://vite.dev/guide/api-environment-frameworks
插件钩子参考、虚拟模块、enforce/apply、handleHotUpdate（项目内部规范子集见 rules/vite-plugin-hooks.md）	https://vite.dev/guide/api-plugin
环境变量和模式、.env 文件、VITE_ 前缀	https://vite.dev/guide/env-and-mode
部署静态站点并使用 vite preview 验证	https://vite.dev/guide/static-deploy

库模式未列在表中：references/library-mode.md 和 rules/vite-lib-config.md 仍完整涵盖此内容。

项目内部差异

阅读 references/ork-delta.md，了解 Vite 文档未说明的规则：现有生产应用采用 Vite 8 的路径、VITE_ 密钥规则、生产环境 sourcemap 设置、项目内部构建预算、vite preview 门槛、advancedChunks 迁移期间的 chunk 名称稳定性、可视化分析器差异对比要求，以及清除 node_modules/.vite 缓存的步骤。

项目内部配置

这不是 Vite 教程：以下配置是上述差异规定的不可妥协项，格式与我们实际交付的配置一致。

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    // 'hidden' emits maps for the error reporter without publishing source.
    // Never true (publishes source) and never 'inline' (inflates every JS file).
    sourcemap: 'hidden',
    rollupOptions: {
      output: {
        // Carry existing chunk NAMES across the manualChunks to advancedChunks
        // migration. A renamed group changes its filename and invalidates that
        // chunk for every returning visitor, even with identical contents.
        advancedChunks: {
          groups: [
            { name: 'vendor', test: /node_modules/, priority: 10 },
            { name: 'app', priority: 0 },
          ],
        },
      },
    },
  },
});

# Prove the build. `vite build` exiting 0 means the bundler finished, not that the
# app runs: base-path mistakes and dev-only env vars survive a green build.
vite build && vite preview      # then walk the routes, console must be clean

# Diff the chunk graph before and after any chunk-config change.
npx vite-bundle-visualizer

# Stale pre-bundle cache mimics a broken plugin. Clear it BEFORE editing plugin code.
rm -rf node_modules/.vite && vite --force

以 VITE_ 为前缀的变量会在构建时内联到客户端 bundle 中。 它们是公开的 bundle 内容，绝不能存放密钥。部署前请检查 .env.production。

规则

规则	涵盖内容
rules/vite-advanced-chunks.md	Chunk 拆分：advancedChunks 分组、优先级、maxSize、minShareCount
rules/vite-environments.md	客户端、SSR 和 edge 的 environments 配置；各环境的 outDir
rules/vite-lib-config.md	库模式外部依赖、双 ESM/CJS 输出、exports 映射、类型声明
rules/vite-plugin-hooks.md	钩子顺序、通过 resolveId + load 创建虚拟模块、enforce 和 apply

关键决策

决策	建议
新项目	Vite 8（默认）
现有生产应用	先通过 rolldown-vite 分阶段升级，再提交更改
多环境构建	Environment API（environments 配置）
插件作用域	在支持环境感知的插件中使用 this.environment
SSR	开发环境使用中间件模式，生产环境使用单独的构建
分块	Vite 8 使用 advancedChunks，兼容 Vite 7 使用 manualChunks

相关技能

• ork:react-server-components-framework - SSR 集成
• ork:storybook-testing - 使用 Vitest 进行组件测试
• ork:performance - 构建预算背后的 Core Web Vitals 目标

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
ork-delta.md	Vite 文档未说明的内部规则
library-mode.md	构建可发布的 npm 包