Vite Plus 迁移记录与踩坑总结

2. 为什么决定迁移到 ViteVite 刚刚发布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代码规范Biomelint formatGit HooksLefthook包管理pnpm pnpm-workspaceNode 版本管理nvmtona/ ├── 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.tsvitest.config.ts中合并到 vite.config.tsbiome.jsonc高迁移到 vite.config.tslefthook.yml高使用 Vite 内置 hooks.nvmrc中使用 Vite 管理 Node 版本package.json scripts高命令重写源码导入语句中vite → vite-plus4. 迁移整体策略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 script is the equivalent of pnpm run script - vp test runs the built-in test command, while vp run test runs the test script from package.json - vp install, vp add, and vp remove delegate through the package manager declared by packageManager - vp dev, vp build, vp preview, vp lint, vp fmt, vp check, and vp pack replace the corresponding standalone tools - Prefer vp check for validation loops Finally, verify the migration by running: vp install, vp check, vp test, and vp build Summarize the migration at the end and report any manual follow-up still required.4.1 迁移原则一次性迁移项目处于活跃开发期适合一次性迁移自动化优先使用 Vite 提供的迁移工具自动处理逐步验证每完成一个阶段立即验证保留回滚能力迁移前创建 git 分支4.2 迁移流程┌─────────────────┐ │ 1. 版本检查 │ 确保 Vite 8, Vitest 4.1 └────────┬────────┘ │ ┌────────▼────────┐ │ 2. 自动迁移 │ 运行 vp migrate --no-interactive └────────┬────────┘ │ ┌────────▼────────┐ │ 3. 配置合并 │ tsdown.config.ts → vite.config.ts └────────┬────────┘ │ ┌────────▼────────┐ │ 4. 清理旧依赖 │ 移除 biome, lefthook, vitest 等 └────────┬────────┘ │ ┌────────▼────────┐ │ 5. 配置迁移 │ 格式化、lint、git hooks └────────┬────────┘ │ ┌────────▼────────┐ │ 6. 验证测试 │ install → check → test → build └─────────────────┘5. 实际迁移步骤5.1 版本检查与安装首先检查现有版本是否满足迁移要求# Vite 要求 Vite 8, Vitest 4.1 vp --version确认满足要求后执行自动迁移vp migrate --no-interactive迁移工具自动完成了以下工作重写vite导入为vite-plus重写vitest导入为vite-plus/test更新package.json中的依赖和 scripts更新pnpm-workspace.yaml5.2 配置合并原 tsdown.config.tsimport { defineConfig } from tsdown export default defineConfig({ platform: browser, entry: [./src/index.ts], format: [esm], dts: true, clean: true, external: [preact], })合并后的 vite.config.tsimport { defineConfig } from vite-plus export default defineConfig({ pack: { platform: browser, entry: [./src/index.ts], format: [esm], dts: true, clean: true, deps: { neverBundle: [preact], }, }, })关键变更说明原配置新配置原因externaldeps.neverBundletsdown 配置已弃用 externalimport from tsdownimport from vite-plus统一从 vite-plus 导入独立文件packblock配置集中管理5.3 格式化配置迁移将 Biome 配置迁移到 vite.config.ts原 biome.jsonc{ formatter: { enabled: true, formatWithErrors: true, indentStyle: space, indentWidth: 2, lineWidth: 80 }, javascript: { formatter: { quoteStyle: single, semicolons: asNeeded, trailingCommas: all } } }迁移后的 vite.config.tsimport { defineConfig } from vite-plus export default defineConfig({ fmt: { singleQuote: true, semi: false, tabWidth: 2, printWidth: 80, trailingComma: all, }, lint: { rules: { no-explicit-any: off, no-non-null-assertion: off, }, }, })踩坑Oxfmt 使用 Prettier 兼容的配置名称而非 Biome 的命名方式。Oxfmt 提供了完整的 Prettier 兼容性配置迁移相对平滑。5.4 Git Hooks 配置移除 Lefthook使用 Vite 内置的 Git hooks# 移除旧配置 rm lefthook.yml # 配置 Vite hooks vp config --hooksVite 会自动配置 pre-commit 钩子执行vp staged命令对暂存文件进行检查。5.5 Node 版本管理移除.nvmrc使用 Vite 管理# 移除旧配置 rm .nvmrc # 固定 Node 版本 vp env pin 22.18.0这会创建.node-version文件Vite 会自动安装和管理对应版本的 Node.js。Vite 会自动检测并使用正确的包管理器pnpm、npm 或 Yarn。5.6 Scripts 更新更新前{ scripts: { test: vitest test, lint: biome check --write, prepare: lefthook install } }更新后{ scripts: { test: vp test, lint: vp lint, fmt: vp fmt, check: vp check } }注意preparescript 已移除Vite 的 hooks 配置由vp config --hooks管理。6. 迁移过程中遇到的坑6.1 类型导入问题问题某些文件使用import type从vite-plus导入类型时dts 生成失败。原因vite-plus的类型定义中引用了vite-plus-test导致类型解析链断裂。解决将类型导入改回vite// 问题代码 import type { Plugin, UserConfig } from vite-plus // 解决方案 import type { Plugin, UserConfig } from vite6.2 CSS 文件名不匹配问题tona-sonner包构建后输出style.css但 package.json exports 定义的是index.css。原因tsdown 默认将 CSS 文件命名为style.css与原配置不一致。解决更新 package.json exports{ exports: { .: { types: ./dist/index.d.mts, import: ./dist/index.mjs }, ./dist/style.css: ./dist/style.css } }更新导入路径// 更新前 import tona-sonner/dist/index.css // 更新后 import tona-sonner/dist/style.css6.3 external 配置弃用问题构建时出现警告external is deprecated. Use deps.neverBundle instead.原因tsdown 更新了配置 API。解决// 更新前 { external: [preact] } // 更新后 { deps: { neverBundle: [preact] } }6.4 单文件输出警告问题使用outputOptions.file配置单文件输出时出现警告[INVALID_OPTION] Warning: Invalid value for option output.dir原因rolldown 内部配置校验问题但构建结果正确。解决暂时接受此警告等待上游修复。配置保持不变{ outputOptions: { file: dist/loader.min.js, }, }6.5 插件兼容性警告问题preact/preset-vite插件触发警告warning: esbuild option was specified by vite:preact-jsx plugin. This option is deprecated, please use oxc instead.原因上游插件尚未适配 Vite 的 oxc 编译器。解决暂时无法解决需等待插件更新。可通过logLevel: warn减少日志输出。6.6 开发脚本适配问题scripts/dev-theme.ts无法正确检测 Vite 服务器启动完成。原因Vite 的启动日志格式与 Vite 不同。解决添加对Local:输出的检测// 更新前 if (data.includes(ready in)) { isReady true } // 更新后 if (data.includes(ready in) || data.includes(Local:)) { isReady true }7. 迁移后的效果7.1 依赖精简迁移前{ devDependencies: { biomejs/biome: ^1.x, lefthook: ^1.x, vite: ^5.x, vitest: ^1.x, tsdown: ^0.x } }迁移后{ devDependencies: { vite-plus: latest } }减少 4 个直接依赖简化了依赖树。7.2 配置文件精简迁移前迁移后vite.config.ts (12个)vite.config.ts (12个)tsdown.config.ts (11个)合并到 vite.config.tsvitest.config.ts (3个)合并到 vite.config.tsbiome.jsonc (1个)合并到 vite.config.tslefthook.yml (1个)移除.nvmrc (1个).node-version (1个)总计从 29 个配置文件减少到 13 个。7.3 构建验证命令结果vp install✅ 成功vp check✅ 0 errors, 22 warningsvp test✅ 205/206 测试通过vp pack(packages)✅ 12 个包构建成功vp build(themes)✅ 3 个主题构建成功7.4 开发体验提升命令统一所有命令以vp开头无需记忆多个工具命令配置集中修改配置只需编辑一个文件版本管理简化工具升级只需更新vite-plus版本性能提升得益于 Rust 底层实现构建和检查速度显著提升7.5 vp check 的优势vp check命令可以在单次运行中完成格式化、lint 和类型检查速度更快$ vp check pass: All 42 files are correctly formatted (88ms, 16 threads) pass: Found no warnings, lint errors, or type errors in 42 files (184ms, 16 threads)7.5 构建耗时大大减少得益于 Vite 缓存机制多包构建耗时明显减少8. 总结8.1 哪些项目适合迁移新项目没有历史包袱可以直接使用 Vite 初始化工具链复杂的项目依赖多个工具配置分散维护成本高monorepo 项目多个包需要统一工具链追求简化配置的项目希望减少配置文件数量对性能有要求的项目需要更快的构建和检查速度8.2 哪些项目不建议迁移依赖特定 Vite 插件的项目某些插件可能尚未适配构建流程高度定制的项目可能需要等待 Vite 支持更多配置选项生产环境稳定性要求极高的项目建议等待 Vite 更加成熟8.3 迁移成本与收益成本时间成本中小型项目约 2-4 小时大型 monorepo 约 1-2 天学习成本需要熟悉 Vite 的配置结构和 CLI 命令兼容性处理可能需要处理插件兼容性问题收益维护成本降低统一工具链减少版本冲突配置简化配置文件数量减少 50%CI/CD 简化无需安装多个工具开发体验提升统一的命令行接口性能提升构建速度提升 40 倍lint 速度提升 50-100 倍8.4 迁移建议先备份迁移前创建 git 分支确保可回滚自动化优先使用vp migrate自动处理大部分工作逐步验证每完成一个阶段立即运行测试和构建保留文档记录迁移过程中的问题和解决方案9. 附录9.1 完整的 vite.config.ts 示例import { defineConfig } from vite-plus export default defineConfig({ // 测试配置 test: { environment: happy-dom, }, // 格式化配置Prettier 兼容 fmt: { singleQuote: true, semi: false, tabWidth: 2, printWidth: 80, trailingComma: all, arrowParens: always, bracketSpacing: true, }, // Lint 配置ESLint 兼容600 规则 lint: { rules: { no-explicit-any: off, no-non-null-assertion: off, no-static-element-interactions: off, }, }, // 库构建配置 pack: { platform: browser, entry: [./src/index.ts], format: [esm], dts: true, clean: true, deps: { neverBundle: [preact], }, }, })9.2 关键文件变更清单文件操作说明vite.config.ts修改导入改为 vite-plustsdown.config.ts删除合并到 vite.config.tsvitest.config.ts删除合并到 vite.config.tsbiome.jsonc删除配置迁移到 vite.config.tslefthook.yml删除使用 Vite hooks.nvmrc删除使用 Vite 管理.node-version新增Vite Node 版本文件package.json修改更新依赖和 scriptspnpm-workspace.yaml修改更新 catalog