如何将现有项目迁移到 Vite+

要将现有项目迁移到 Vite+，请新建一个分支，在项目根目录或工作区根目录下运行 vp migrate。在任何文件被修改之前，先阅读它输出的迁移计划；迁移完成后，依次运行 vp install、vp check、vp test 和 vp build（库项目则运行 vp pack）确认结果，然后再更新 CI。

把一个正常运行、拥有五套独立工具配置的仓库迁移到新的工具链上，这类改动在 PR 标题里看起来微不足道，实际却可能占用一整个迭代周期。问题通常出现在自动化步骤完成之后：它转换了哪些内容，又遗漏了哪些内容。

本指南面向已经在使用 Vite、Vitest、ESLint 和 Prettier 的项目，内容涵盖 vp migrate 会修改什么、会把哪些工作留给你、迁移后需要检查什么，以及如何更新 GitHub Actions 和 GitLab CI。如果你需要先了解 Vite+ 及其命令的概况，请从 Vite+ 入门开始阅读。Vite+ 1.0 于 2026 年 9 月 28 日发布，采用 MIT 许可证。

哪些团队适合迁移到 Vite+？迁移后能获得什么？

如果你的团队需要分别维护 Vite、Vitest、ESLint、Prettier 以及 tsup 或 tsdown 等库打包工具的配置，就很适合迁移。迁移完成后，你只需一个 vite-plus 依赖和一个 vite.config.ts，其中统一管理开发、测试、lint、格式化和打包（pack）设置。tsup 属于受支持的迁移来源，因此使用 tsup 打包的 TypeScript 库也可以一并迁移。不过，请做好后续处理的准备。迁移指南明确指出，大多数项目在命令执行完毕后仍需进行一些手动调整。

运行 vp migrate 之前需要做哪些准备？

请在独立分支上、从干净的工作区开始执行 Vite+ 迁移。这样 diff 中只包含迁移相关的改动，需要时也可以轻松丢弃。

git switch -c chore/migrate-vite-plus
git status   # should report a clean tree

开始之前，请确认以下三项：

• Vite 7 或更高版本。 较旧的项目需要先升级 Vite。Vite 7 新特性介绍了该版本的变化。
• Vitest 4 或更高版本。 迁移前请先将较旧的测试套件升级到 v4。
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0，详见 Vitest 5 升级指南。

请先完成上述上游升级并验证通过，然后保留现有的 lockfile 和已安装的依赖包。迁移工具会读取它们，以判断你原先使用的 Vitest 版本。

运行 vp migrate 并阅读迁移计划

不带参数运行 vp migrate 会迁移当前目录。它会在写入任何文件之前展示计划中的改动。若要迁移其他目录中的项目，请传入相应路径。

vp migrate                    # interactive, migrates the current directory
vp migrate ./path/to/project  # migrate another directory
vp migrate --no-interactive   # scripted runs

migrate 命令支持以下参数：

• --no-interactive：以非交互方式运行，不显示提示。
• --agent <name> / --no-agent：控制是否设置编码智能体（coding agent）的指令文件。
• --editor <name> / --no-editor：控制是否写入编辑器配置。
• --hooks / --no-hooks：控制是否设置 git hooks。

在 monorepo 中，vp migrate 唯一有效的目标是工作区根目录。它所改写的 lockfile、catalog 和包管理器设置属于工作区中的所有包，因此只需在根目录运行一次，不要逐个包运行。

vp migrate 会转换哪些内容？又会保留哪些内容？

vp migrate 会更新依赖、改写导入语句、将工具配置合并到 vite.config.ts、更新 package.json 脚本，并对其修改过的文件进行格式化。它会刻意保留现有的 git hook 工具不做改动。

测试中的导入语句会从上游 Vitest 切换为 vite-plus 中的重导出（vite-plus 内置了 Vitest 5）。类型扩充（type augmentation）则仍然指向上游的 vitest：

// before
import { defineConfig } from 'vitest/config'
import { describe, it, expect } from 'vitest'

// after
import { defineConfig } from 'vite-plus'
import { describe, it, expect } from 'vite-plus/test'

declare module 'vitest' {
  // unchanged: augmentations keep targeting upstream vitest
}

如果你保留了 hook 工具，lint-staged 也会随之保留，因为 vp staged 只读取 vite.config.ts 中的 staged 配置块。你需要手动切换：

import { defineConfig } from 'vite-plus'

export default defineConfig({
  staged: {
    '*.{js,ts,tsx}': 'vp check --fix',
  },
})

对于使用低于 0.23 版本 tsdown 的库（或无法检测到已安装版本时），迁移会沿用旧的默认行为：如果你尚未设置 deps.resolveDepSubpath，会在 pack 配置块中添加 deps.resolveDepSubpath: true；如果启用了 ATTW 检查且未设置 profile，则会添加 attw.profile: 'strict'。完整的转换规则请参阅迁移规则文档。

如何验证迁移后的项目？

依次运行 vp install、vp check、vp test 和 vp build（库项目则运行 vp pack），并在提交前逐一审查结果。由于迁移会对修改过的文件运行格式化工具，请将格式化改动与依赖、配置和导入语句的改动分开审查，否则格式化产生的 diff 可能会掩盖逻辑上的改动。

提交前请阅读迁移生成的审查报告。如果你有浏览器模式、覆盖率或基准测试套件，也请分别单独运行。

lint 或格式化规则未能迁移怎么办？

迁移工具会尽可能将 ESLint flat config 转换为 Oxlint 配置、将 Prettier 配置转换为 Oxfmt 配置，但并非每条 ESLint 规则都有对应的 Oxlint 规则。vp migrate 会列出它跳过的不受支持的规则。如果你依赖的某条规则未能迁移，可以将原工具保留为项目脚本，并通过 vp run 运行：

{ "scripts": { "lint:eslint": "eslint ." } }

vp run lint:eslint

这种做法的前提是 ESLint 脚本在迁移后依然保留，即你拒绝了 ESLint/Prettier 转换提示，或者项目使用的是旧版 .eslintrc。否则，你需要在迁移后自行重新添加依赖包、配置和脚本。请注意，vp test 始终运行内置的测试命令，而 vp run test 运行的是 package.json 中定义的 test 脚本。

如果 Node 或包管理器解析到了错误的版本，请运行 vp env doctor 进行诊断。

如何为 Vite+ 更新 CI？

在 CI 中，Vite+ 的 setup action 取代了原先分别负责 Node、包管理器、依赖安装和缓存的多个步骤，各个 job 直接调用 vp 命令即可。在 GitHub Actions 中，setup-vp 默认会安装依赖，除非你设置了 run-install: false：

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: voidzero-dev/setup-vp@<setup-vp-version>
        with:
          node-version: '24'
          cache: true
      - run: vp check
      - run: vp test
      - run: vp build

在 GitLab 中，按照 CI 指南的要求，需要 include 远程的 setup-vp.yml 模板、继承 .setup-vp，并使用已预装 Node 的镜像：

include:
  # copy the exact remote URL from the Vite+ CI guide
  - remote: 'https://raw.githubusercontent.com/voidzero-dev/setup-vp/<setup-vp-version>/gitlab/setup-vp.yml'
    inputs:
      setup-ref: '<setup-vp-version>'

check:
  extends: .setup-vp
  image: node:24
  # caching uses GitLab's native cache: keyword
  script:
    - vp check
    - vp test
    - vp build

请将 setup-vp 锁定到确切的发布标签或 commit SHA，而不是使用 v1，因为 VoidZero 已不再更新该标签。请在工作流中搜索 setup-vp@v1 并进行替换。在 GitLab 中，版本号会出现两次（一次在 include URL 中，一次在 setup-ref 中），升级时需要手动同时更新这两处。

总结

要让 Vite+ 迁移顺利进行，关键在于把 vp migrate 视为第一步，而不是全部工作。阅读它的迁移计划，将格式化改动与逻辑改动分开审查，运行四条验证命令，并在合并之前于 CI 中锁定 setup-vp 版本。接下来，新建分支，运行 vp migrate，并逐一处理它针对 hooks 和 lint 规则输出的警告。

常见问题

在已经使用 Vite+ 的项目上运行 vp migrate 会发生什么？

它只会升级工具链：将所有工作区包的依赖和包管理器设置更新为执行迁移的 CLI 所内置的版本，并完成导入语句的最终调整。它会跳过 git hooks、编辑器和智能体文件、lint 迁移等首次设置操作。传入 --full 可同时执行这些设置操作。请先运行 vp upgrade，确保全局 CLI 拥有最新的迁移规则。

我应该使用项目自身 node_modules 中的 vp 来运行 vp migrate 吗？

不应该。Vite+ 迁移指南明确指出，不要使用旧项目的 node_modules/.bin/vp 执行迁移。请使用全局安装的 vp，或通过 npx --package=vite-plus@version vp migrate（或等效的 pnpm dlx 命令）获取目标版本。这样可以在不预先替换项目旧依赖的情况下加载目标 CLI，迁移工具也就仍能检测出你原先使用的 Vitest 版本。

迁移后 Vite+ 支持哪些包管理器？

Vite+ 支持 pnpm、npm、Yarn 和 Bun。它会根据工作区根目录下的文件（例如 packageManager 字段和 lockfile）检测包管理器，若均未找到则回退到 pnpm。之后，vp install 会针对检测到的包管理器执行相应的安装行为，包括使用正确的 lockfile 参数。

如何知道迁移丢弃了哪些 ESLint 规则？

vp migrate 会报告在转换为 Oxlint 过程中跳过的不受支持的 ESLint 规则。该功能自 Vite+ 0.3.2 起提供，方便你审查会失去哪些检查。请在提交前逐一查看该列表，然后通过将 ESLint 保留为项目脚本并借助 vp run 运行的方式，重新加入你需要的规则。