vite-v8

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vite 8 Skill

Vite 8 技能指南

Configure, migrate, and debug Vite 8 projects with the repo's preferred Vite-native patterns.

使用仓库推荐的Vite原生模式来配置、迁移和调试Vite 8项目。

Before You Start

开始之前

This skill focuses on the Vite 8 architecture shift, not generic bundler advice.

Metric	Without Skill	With Skill
Migration Time	~120 min	~40 min
Common Config Errors	6+	0
Token Usage	High (trial/error)	Low (known patterns)

本技能聚焦于Vite 8的架构转变，而非通用打包工具建议。

指标	未使用本技能	使用本技能
迁移时间	~120分钟	~40分钟
常见配置错误	6+	0
Token 消耗	高（反复试错）	低（采用成熟模式）

Known Issues This Skill Prevents

本技能可避免的已知问题

Broken builds from leaving
```
rollupOptions
```
in Vite 8 configs where
```
rolldownOptions
```
is needed
Outdated JS/TS transform setup from using
```
esbuild
```
instead of
```
oxc
```
Plugin code checking stale
```
ssr
```
booleans instead of environment-aware APIs
HMR bugs from using deprecated
```
handleHotUpdate
```
patterns instead of
```
hotUpdate
```
SSR/runtime confusion from older
```
ssrLoadModule
```
mental models instead of Module Runner
Performance regressions from missing hook filters in Rust↔JS plugin boundaries
Slow startup and request waterfalls from barrel files, missing warmup, or loose import resolution

在Vite 8配置中保留
```
rollupOptions
```
而非使用所需的
```
rolldownOptions
```
导致构建失败
使用
```
esbuild
```
而非
```
oxc
```
进行JS/TS转换配置，导致配置过时
插件代码检查过时的
```
ssr
```
布尔值，而非使用感知环境的API
使用已弃用的
```
handleHotUpdate
```
模式而非
```
hotUpdate
```
导致HMR错误
仍沿用旧版
```
ssrLoadModule
```
思维模型，而非Module Runner，引发SSR/运行时混淆
在Rust↔JS插件边界缺少钩子过滤器导致性能下降
由于桶文件、缺失预热或松散的导入解析，导致启动缓慢和请求瀑布问题

Quick Start

快速开始

Step 1: Start with a typed Vite 8 config

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

typescript

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

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

Why this matters: Vite 8 is built around Rolldown/Oxc-era config and defaults. Starting from

defineConfig

with Vite 8 options avoids backporting old Rollup/esbuild assumptions into a new architecture.

typescript

// 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时代的配置和默认值构建。从带有Vite 8选项的

defineConfig

开始，可避免将旧的Rollup/esbuild假设带入新架构。

Step 2: Prefer Vite 8 terminology in plugins and SSR code

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

typescript

import type { Plugin } from 'vite';

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

Why this matters: Vite 8 leans on named environments and environment-aware plugin behavior. That is a better fit than older client-vs-SSR shortcuts.

typescript

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快捷方式更适配。

Step 3: Use the correct one-shot commands

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

bash

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

Why this matters: These are the stable command surfaces agents and CI flows should target. Avoid inventing framework-specific abstractions unless the project already uses them.

bash

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

为何重要： 这些是Agent和CI流程应瞄准的稳定命令接口。除非项目已在使用，否则避免创建框架特定的抽象。

Critical Rules

关键规则

Always Do

必须执行

Use
```
vite.config.ts
```
with
```
defineConfig
```
for repo-facing Vite 8 work

Prefer

build.rolldownOptions

over legacy

build.rollupOptions

Prefer
```
oxc
```
over
```
esbuild
```
for new Vite 8 transform configuration
Use named environments when plugin or SSR behavior differs by runtime
Use hook filters when writing performance-sensitive
```
transform
```
or
```
resolveId
```
plugins
Reach for Module Runner concepts when debugging modern SSR/runtime execution
Use explicit file extensions and review barrel files when performance work matters
Keep Vite plugin code ESM-first

在面向仓库的Vite 8工作中，使用带有
```
defineConfig
```
的
```
vite.config.ts
```

优先使用

build.rolldownOptions

而非旧版

build.rollupOptions

在新的Vite 8转换配置中，优先使用
```
oxc
```
而非
```
esbuild
```
当插件或SSR行为因运行时不同而有差异时，使用命名环境
编写性能敏感的
```
transform
```
或
```
resolveId
```
插件时，使用钩子过滤器
调试现代SSR/运行时执行时，采用Module Runner概念
当涉及性能优化时，使用明确的文件扩展名并检查桶文件
保持Vite插件代码为ESM优先

Never Do

禁止执行

Never introduce new
```
rollupOptions
```
/
```
esbuild
```
examples as the preferred Vite 8 path
Never treat
```
handleHotUpdate
```
as the forward-looking HMR hook in Vite 8
Never assume a single client/SSR split is enough for all runtimes
Never suggest CommonJS config as the default for new Vite work
Never skip
```
ssr.noExternal
```
review when SSR dependencies misbehave

切勿将新的
```
rollupOptions
```
/
```
esbuild
```
示例作为Vite 8的首选方案
切勿将
```
handleHotUpdate
```
视为Vite 8中具有前瞻性的HMR钩子
切勿假设单一的客户端/SSR拆分足以覆盖所有运行时
切勿建议将CommonJS配置作为新Vite项目的默认选项
当SSR依赖表现异常时，切勿跳过
```
ssr.noExternal
```
检查

Common Mistakes

常见错误

Wrong - legacy build config:

typescript

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

Correct - Vite 8 config:

typescript

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

Why: Vite 8 moved its preferred build and transform configuration surface to Rolldown and Oxc.

Wrong - stale HMR hook:

typescript

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

Correct - environment-aware HMR:

typescript

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

Why:

hotUpdate

is the environment-aware Vite 8 direction, while

handleHotUpdate

is legacy-oriented.

错误示例 - 旧版构建配置：

typescript

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

正确示例 - Vite 8配置：

typescript

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

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

错误示例 - 过时的HMR钩子：

typescript

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

正确示例 - 感知环境的HMR：

typescript

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

原因：

hotUpdate

是Vite 8中感知环境的发展方向，而

handleHotUpdate

属于旧版实现。

Known Issues Prevention

已知问题预防

Issue	Root Cause	Solution
Config migration stalls	Old Rollup/esbuild settings copied forward	Migrate to `rolldownOptions` and `oxc`
Plugin logic breaks in non-standard runtimes	Plugin assumes only client/SSR	Use named `environments` and `this.environment`
HMR customization feels brittle	Legacy HMR hook carried forward	Prefer `hotUpdate` and environment-aware flows
SSR dependency crashes	Externalization assumptions are wrong	Review `ssr.noExternal` and runtime-specific needs
Dev/build behavior diverges	Config ignores Vite 8's unified engine model	Validate both `vite dev` and `vite build` under Rolldown
Plugin performance drops	Too much JS-side hook work	Add hook filters and narrower matching
Cold starts are sluggish	Heavy hot paths are not warmed and import graph is noisy	Review `server.warmup` , explicit extensions, and barrel-file usage

问题	根本原因	解决方案
配置迁移停滞	旧的Rollup/esbuild设置被直接沿用	迁移至 `rolldownOptions` 和 `oxc`
插件逻辑在非标准运行时中失效	插件仅假设存在客户端/SSR两种环境	使用命名 `environments` 和 `this.environment`
HMR定制不稳定	沿用旧版HMR钩子	优先使用 `hotUpdate` 和感知环境的流程
SSR依赖崩溃	外部化假设错误	检查 `ssr.noExternal` 和运行时特定需求
开发/构建行为不一致	配置忽略Vite 8的统一引擎模型	在Rolldown下验证 `vite dev` 和 `vite build`
插件性能下降	JS端钩子工作负载过大	添加钩子过滤器和更精确的匹配规则
冷启动缓慢	核心热路径未预热且导入图杂乱	检查 `server.warmup` 、明确扩展名和桶文件使用情况

Bundled Resources

附带资源

References

参考文档

Core config and CLI patterns →
```
references/core-config-reference.md
```

Environment-aware plugin authoring →

references/plugin-environment-reference.md

Build, SSR, and migration guidance →

references/build-ssr-migration-reference.md

Performance and dev-server heuristics →

references/performance-devserver-reference.md

Reference index →
```
references/README.md
```

核心配置与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
```

Configuration Reference

配置参考

vite.config.ts

typescript

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: {},
  },
});

Key settings:

```
build.rolldownOptions
```
: Preferred Vite 8 build customization surface
```
oxc
```
: Preferred JS/TS transform configuration surface in new Vite 8 examples
```
environments
```
: Use when runtime behavior differs across client/SSR/edge-like targets
```
css.lightningcss
```
: Reflects Vite 8's modern CSS processing direction
```
server.warmup
```
: Useful in large apps where cold-start waterfalls hit the same hot files repeatedly

typescript

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
```
: 在冷启动瀑布效应反复影响相同核心文件的大型应用中非常有用

Project Structure

项目结构

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

Why this matters: Vite 8 still rewards simple, explicit project layout. Complexity should come from runtime environments and plugin boundaries, not from hiding the core config.

Performance heuristic: If startup feels bad, inspect import-graph shape before chasing exotic bundler flags. Barrel files, omitted extensions, and lack of warmup often matter more than another layer of config cleverness.

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

为何重要： Vite 8仍然青睐简洁、明确的项目布局。复杂度应来自运行时环境和插件边界，而非隐藏核心配置。

性能启发式建议： 如果启动速度慢，先检查导入图的结构，再去寻找复杂的打包器配置。桶文件、缺失的扩展名和未预热通常比额外的配置技巧更影响性能。

Common Patterns

常见模式

Environment-aware plugin pattern

感知环境的插件模式

typescript

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'],
          },
        };
      }
    },
  };
}

typescript

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 build pattern

SSR构建模式

bash

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

bash

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

Module Runner mental model

Module Runner 思维模型

typescript

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

Use this model when modern Vite SSR debugging is really about runtime execution boundaries rather than plain bundling.

typescript

// 伪代码示例
const mod = await moduleRunner.import('/src/entry-server.ts');

当现代Vite SSR调试实际关乎运行时执行边界而非单纯打包时，使用此模型。

Dependencies

依赖项

Required

必填

Package	Version	Purpose
`vite`	^8	Build tool, dev server, plugin host
`node`	>=20.19 or >=22.12	Required Vite 8 runtime

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

Optional

可选

Package	Version	Purpose
`typescript`	latest	Typed `vite.config.ts` and plugin authoring
framework plugin packages	latest	React/Vue/Svelte/etc integrations

包	版本	用途
`typescript`	最新版	类型化的 `vite.config.ts` 和插件开发
框架插件包	最新版	React/Vue/Svelte等框架集成

Official Documentation

官方文档

Troubleshooting

故障排查

Old config keys no longer feel right

旧配置键不再适用

Symptoms: A config works but reads like pre-Vite-8 code, or new options are not behaving as expected.

Solution:

typescript

build: {
  rolldownOptions: {},
}

oxc: {}

症状： 配置可以运行，但写法类似Vite 8之前的代码，或者新选项未按预期工作。

解决方案：

typescript

build: {
  rolldownOptions: {},
}

oxc: {}

SSR runtime behavior is unclear

SSR运行时行为不明确

Symptoms: The bundle builds, but runtime execution differs by environment or platform.

Solution: Review

environments

this.environment

, Module Runner expectations, and

ssr.noExternal

before changing unrelated bundler settings.

症状： 打包成功，但运行时行为因环境或平台而异。

解决方案： 在修改无关的打包器设置之前，先检查

environments

、

this.environment

、Module Runner预期和

ssr.noExternal

。

Plugin hook work feels slow or noisy

插件钩子工作缓慢或冗余

Symptoms: Custom plugins add overhead in dev or build.

Solution: Use hook filters and narrow matching patterns so only relevant files cross the Rust↔JS boundary.

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

解决方案： 使用钩子过滤器和精确的匹配模式，仅让相关文件跨越Rust↔JS边界。

Setup Checklist

设置检查清单

Before using this skill, verify:

```
vite
```
is on a Vite 8 release line
Node satisfies Vite 8 runtime requirements
```
vite.config.ts
```
is ESM/TypeScript-first
Legacy
```
rollupOptions
```
/
```
esbuild
```
usage has been reviewed
Environment-specific behavior is modeled explicitly when SSR/edge runtimes are involved

使用本技能前，请验证：

```
vite
```
处于Vite 8版本线
Node满足Vite 8的运行时要求
```
vite.config.ts
```
采用ESM/TypeScript优先
已检查旧版
```
rollupOptions
```
/
```
esbuild
```
的使用情况
当涉及SSR/边缘运行时时，已明确建模环境特定行为