Vite Plus 迁移记录与踩坑总结

本文记录了将 Tona 项目从传统 Vite 工具链完整迁移到 Vite+ 的全过程，包括迁移策略、配置调整、踩坑经历与最终收益。

1. 项目背景

Tona 是一个专为博客园设计的皮肤开发框架，采用 monorepo 架构，包含：

12 个 packages：核心库、UI 组件、Hooks、工具函数、CLI 工具等
3 个 themes：geek、reacg、shadcn 三套博客皮肤

关于 Tona 的详细介绍，请查看这篇博文《AI × 博客园皮肤》。

更详细的介绍

2. 为什么决定迁移到 Vite+

Vite+ 刚刚发布，MIT 协议，免费且开源。我十分喜欢 Vite 的 API 的设计和兼容性，对于 Tona， Vite 几乎每个版本都有经历，从 Vite 0.8 版本开始使用，逐步过渡到 Vite 8，每次升级都轻而易举，相信这次也不例外！

Vite+ 将现代 Web 开发所需的工具整合到一个统一的工具链中：

工具	用途
Vite + Rolldown	开发服务器和应用构建
Vitest	测试框架
Oxlint + Oxfmt	代码检查和格式化
tsdown	库构建和独立可执行文件
Vite Task	任务编排

统一的工作流：

vp dev      # 开发服务器
vp check    # 格式化 + lint + 类型检查
vp test     # 运行测试
vp build    # 生产构建
vp run      # 任务执行

在 JavaScript 生态中，开发者需要管理越来越多的工具：运行时（Node.js）、包管理器（pnpm/npm/yarn）、开发服务器、linter、formatter、测试运行器、打包器、任务运行器……每个工具都有自己的配置文件、版本管理和升级周期。

一个典型的前端项目需要配置多个工具：

{
  "devDependencies": {
    "vite": "^5.x",
    "vitest": "^1.x",
    "tsdown": "^0.x",
    "@biomejs/biome": "^1.x",
    "lefthook": "^1.x"
  }
}

每个工具都有独立的配置文件、版本管理、升级周期。当它们之间存在兼容性问题时，调试成本极高。

tona/
├── vite.config.ts
├── vitest.config.ts
├── tsdown.config.ts
├── biome.jsonc
├── lefthook.yml
└── .nvmrc

配置分散在多个文件中，维护成本高，且容易出现配置不一致的问题。How many config files does one need, right?

每个工具都需要单独安装和更新，版本冲突时有发生。特别是 tsdown 和 Vite 之间的依赖关系，经常导致 lock 文件冲突。正如 Vite+ 官方文档所指出的，这些问题在多团队组织中会被放大：依赖管理、构建基础设施和代码质量成为分散的责任，每个团队各自处理，往往没有人将其作为优先事项来负责。结果是依赖版本不同步、构建变慢、代码质量下降。

Vite+ 的底层组件使用 Rust 编写，提供了企业级的性能：

操作	性能提升
生产构建	比 webpack 快 40 倍
代码检查	比 ESLint 快 50-100 倍
代码格式化	比 Prettier 快 30 倍

更重要的是，统一工具链带来了额外的性能优势。例如，vp check 可以在单次运行中同时完成格式化、lint 和类型检查，比分开运行类型感知的 lint 规则和类型检查快 2 倍。

对于 Tona 这样一个 monorepo 项目，Vite+ 的价值尤为明显：

减少依赖数量：移除 5 个工具依赖，简化 package.json
统一配置管理：12 个 package 的配置风格统一
简化 CI/CD：无需在 CI 中安装多个工具
降低维护成本：工具升级只需更新 Vite+ 版本
性能提升：构建和检查速度显著提升

3. 迁移前的项目结构和技术栈

原有技术栈

类别	工具/方案
构建工具	Vite + tsdown
测试框架	Vitest
代码规范	Biome（lint + format）
Git Hooks	Lefthook
包管理	pnpm + pnpm-workspace
Node 版本管理	nvm

tona/
├── packages/
│   ├── core/
│   │   ├── vite.config.ts
│   │   └── tsdown.config.ts      # 库构建配置
│   ├── hooks/
│   ├── ui/
│   ├── utils/
│   └── ...
├── themes/
│   ├── geek/
│   │   └── vite.config.ts
│   ├── shadcn/
│   │   └── vite.config.ts
│   └── reacg/
│       └── vite.config.ts
├── vite.config.ts                # 根配置
├── vitest.config.ts              # 测试配置
├── biome.jsonc                   # 代码规范
├── lefthook.yml                  # Git hooks
├── .nvmrc                        # Node 版本
└── pnpm-workspace.yaml

受影响的部分：

部分	影响程度	说明
vite.config.ts	高	需要重写导入和配置结构
tsdown.config.ts	高	合并到 vite.config.ts
vitest.config.ts	中	合并到 vite.config.ts
biome.jsonc	高	迁移到 vite.config.ts
lefthook.yml	高	使用 Vite+ 内置 hooks
.nvmrc	中	使用 Vite+ 管理 Node 版本
package.json scripts	高	命令重写
源码导入语句	中	vite → vite-plus

4. 迁移整体策略

Vite+ 提供了 coding agent 专用的迁移提示词，我先让 agent 走一遍再手动处理剩余问题。

Migrate this project to Vite+. Vite+ replaces the current split tooling around runtime management, package management, dev/build/test commands, linting, formatting, and packaging. Run `vp help` to understand Vite+ capabilities and `vp help migrate` before making changes. Use `vp migrate --no-interactive` in the workspace root. Make sure the project is using Vite 8+ and Vitest 4.1+ before migrating.

After the migration:

- Confirm `vite` imports were rewritten to `vite-plus` where needed
- Confirm `vitest` imports were rewritten to `vite-plus/test` where needed
- Remove old `vite` and `vitest` dependencies only after those rewrites are confirmed
- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`

Command mapping to keep in mind:

- `vp run