vite-v8

Vite 8 技能

使用项目首选的 Vite 原生模式配置、迁移和调试 Vite 8 项目。

开始之前

此技能专注于 Vite 8 的架构转变，而非通用打包器建议。

指标	不使用技能	使用技能
迁移时间	~120 分钟	~40 分钟
常见配置错误	6+	0
Token 用量	高（反复试错）	低（已知模式）

此技能可避免的已知问题

1. 在 Vite 8 配置中保留 rollupOptions，而需要使用 rolldownOptions，导致构建失败
2. 使用 esbuild 而不是 oxc，导致 JS/TS 转换配置过时
3. 插件代码检查过时的 ssr 布尔值，而不是环境感知 API
4. 使用已弃用的 handleHotUpdate 模式，而不是 hotUpdate，导致 HMR 问题
5. 沿用旧版 ssrLoadModule 思维模式，而不是 Module Runner，造成 SSR/运行时认知混乱
6. Rust↔JS 插件边界缺少钩子过滤器，导致性能退化
7. 桶文件、缺少预热或宽松的导入解析导致启动缓慢、请求瀑布

快速开始

步骤 1：从类型化的 Vite 8 配置开始

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

export default defineConfig({
  server: {
    port: 5173,
  },
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
});

为何重要： Vite 8 围绕 Rolldown/Oxc 时代的配置和默认设置构建。从 defineConfig 和 Vite 8 选项入手，可避免将旧的 Rollup/esbuild 假设移植到新架构中。

步骤 2：在插件和 SSR 代码中优先使用 Vite 8 术语

import type { Plugin } from 'vite';

export function inspectEnvironment(): Plugin {
  return {
    name: 'inspect-environment',
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

为何重要： Vite 8 依赖命名环境和环境感知的插件行为。相比旧版客户端与 SSR 的快捷划分，这种方式更合适。

步骤 3：使用正确的一次性命令

vite dev
vite build
vite build --ssr src/entry-server.ts
vite preview

为何重要： 这些是 Agent 和 CI 工作流应当使用的稳定命令接口。除非项目已在使用，否则不要自行设计框架专属抽象。

关键规则

务必做到

• 面向代码库的 Vite 8 工作使用 vite.config.ts 和 defineConfig
• 优先使用 build.rolldownOptions，而非旧版 build.rollupOptions
• 新的 Vite 8 转换配置优先使用 oxc，而非 esbuild
• 插件或 SSR 行为因运行时而异时，使用命名环境
• 编写对性能敏感的 transform 或 resolveId 插件时，使用钩子过滤器
• 调试现代 SSR/运行时执行时，采用 Module Runner 概念
• 重视性能时，使用显式文件扩展名并检查桶文件
• Vite 插件代码优先采用 ESM

切勿这样做

• 切勿将新的 rollupOptions/esbuild 示例作为首选的 Vite 8 方案
• 切勿将 handleHotUpdate 视为 Vite 8 面向未来的 HMR 钩子
• 切勿假设单一的客户端/SSR 划分足以覆盖所有运行时
• 切勿建议将 CommonJS 配置作为新 Vite 项目的默认方案
• SSR 依赖出现异常时，切勿跳过对 ssr.noExternal 的检查

常见错误

错误 - 旧版构建配置：

export default defineConfig({
  build: {
    rollupOptions: {
      external: ['react'],
    },
  },
  esbuild: {
    jsxInject: "import React from 'react'",
  },
});

正确 - Vite 8 配置：

export default defineConfig({
  build: {
    rolldownOptions: {
      external: ['react'],
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
});

原因： Vite 8 已将首选的构建和转换配置接口转向 Rolldown 和 Oxc。

错误 - 过时的 HMR 钩子：

export default function plugin() {
  return {
    name: 'old-hmr',
    handleHotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

正确 - 环境感知的 HMR：

export default function plugin() {
  return {
    name: 'env-hmr',
    hotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

原因： hotUpdate 是 Vite 8 面向环境感知的方向，而 handleHotUpdate 面向旧版模式。

已知问题预防

问题	根本原因	解决方案
配置迁移停滞	复制沿用了旧版 Rollup/esbuild 设置	迁移到 rolldownOptions 和 oxc
插件逻辑在非标准运行时中失效	插件假设只有客户端/SSR	使用具名 environments 和 this.environment
HMR 自定义难以维护	沿用了旧版 HMR 钩子	优先使用 hotUpdate 和感知环境的流程
SSR 依赖崩溃	外部化假设有误	检查 ssr.noExternal 和运行时特定需求
开发/构建行为不一致	配置忽略了 Vite 8 的统一引擎模型	在 Rolldown 下验证 vite dev 和 vite build
插件性能下降	在 JS 侧的钩子中执行了过多工作	添加钩子过滤器并缩小匹配范围
冷启动缓慢	繁重的热点路径未预热，且导入图过于复杂	检查 server.warmup、显式扩展名和 barrel 文件的使用

打包资源

参考资料

• 核心配置和 CLI 模式 → references/core-config-reference.md
• 编写感知环境的插件 → references/plugin-environment-reference.md
• 构建、SSR 和迁移指南 → references/build-ssr-migration-reference.md
• 性能和开发服务器启发式 → references/performance-devserver-reference.md
• 参考资料索引 → references/README.md

配置参考

vite.config.ts

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        chunkFileNames: 'assets/[name]-[hash].js',
      },
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
  environments: {
    ssr: {
      resolve: {
        conditions: ['node'],
      },
    },
  },
  css: {
    lightningcss: {},
  },
});

关键设置：

• build.rolldownOptions：Vite 8 首选的构建自定义接口
• oxc：新版 Vite 8 示例中首选的 JS/TS 转换配置接口
• environments：当客户端/SSR/类边缘运行环境的行为存在差异时使用
• css.lightningcss：体现了 Vite 8 现代化的 CSS 处理方向
• server.warmup：适用于大型应用，可在冷启动时反复访问相同热点文件的场景

项目结构

my-app/
├── src/
├── index.html
├── vite.config.ts
├── package.json
└── tsconfig.json

为何重要： Vite 8 仍然推崇简单、明确的项目布局。复杂性应来自运行时环境和插件边界，而不是隐藏核心配置。

性能启发式： 如果启动体验不佳，应先检查导入图结构，再考虑不常见的打包器标志。与其再增加一层巧妙的配置，不如优先检查 barrel 文件、缺失的扩展名和未配置预热等问题。

常见模式

感知环境的插件模式

import type { Plugin } from 'vite';

export function envAwarePlugin(): Plugin {
  return {
    name: 'env-aware-plugin',
    transform: {
      filter: {
        id: /\.(ts|tsx)$/,
      },
      handler(code, id) {
        return {
          code,
          map: null,
        };
      },
    },
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

SSR 构建模式

vite build
vite build --ssr src/entry-server.ts
vite preview

Module Runner 心智模型

// Pseudocode sketch
const mod = await moduleRunner.import('/src/entry-server.ts');

当现代 Vite SSR 调试实际涉及运行时执行边界，而非普通打包时，请使用此模型。

依赖项

必需

包	版本	用途
vite	^8	构建工具、开发服务器、插件宿主
node	>=20.19 or >=22.12	Vite 8 所需的运行时

可选

包	版本	用途
typescript	latest	为 vite.config.ts 和插件开发提供类型支持
framework plugin packages	latest	React/Vue/Svelte 等集成

官方文档

• Vite 文档
• LLM 索引
• 配置参考
• 插件 API
• 构建指南
• SSR 指南
• 环境 API

故障排除

旧配置键不再合适

症状： 配置可以运行，但看起来像 Vite 8 之前的代码，或者新选项未按预期生效。

解决方案：

build: {
  rolldownOptions: {},
}

oxc: {}

SSR 运行时行为不明确

症状： 构建成功，但运行时执行效果因环境或平台而异。

解决方案： 在更改无关的打包器设置之前，先检查 environments、this.environment、Module Runner 的预期行为以及 ssr.noExternal。

插件钩子运行缓慢或产生过多干扰

症状： 自定义插件在开发或构建过程中增加了开销。

解决方案： 使用钩子过滤器和范围更精确的匹配模式，确保只有相关文件会跨越 Rust↔JS 边界。

设置检查清单

使用此技能之前，请确认：

• vite 属于 Vite 8 发布系列
• Node 满足 Vite 8 的运行时要求
• vite.config.ts 采用 ESM/TypeScript 优先的方式
• 已检查旧版 rollupOptions / esbuild 的用法
• 涉及 SSR/边缘运行时时，已明确建模特定环境的行为