Vite+

迁移到 Vite+ ​

vp migrate 帮助将现有项目迁移到 Vite+。

概述 ​

此命令是将独立的 Vite、Vitest、Oxlint、Oxfmt、ESLint、Prettier 和 tsup 设置整合到 Vite+ 的起点。

当您想将一个现有项目迁移到 Vite+ 默认配置，而不是手动连接每个工具时，请使用此命令。

用法 ​

bash
vp migrate
vp migrate <path>
vp migrate --no-interactive

目标路径 ​

位置参数 PATH 是可选的。

  • 如果省略，vp migrate 会迁移当前目录
  • 如果提供，则会迁移指定的目标目录
  • 对于 monorepo，目标必须是工作区根目录。Vite+ 无法迁移单个工作区成员，因为迁移会更新所有成员共享的包管理器配置、catalog 和 lockfile
bash
vp migrate
vp migrate my-app

选项 ​

  • --agent <name> 将代理指令写入项目
  • --no-agent 跳过代理指令设置
  • --editor <name> 将编辑器配置文件写入项目
  • --no-editor 跳过编辑器配置设置
  • --hooks 设置预提交钩子
  • --no-hooks 跳过钩子设置
  • --no-interactive 在无提示模式下运行迁移。

迁移流程 ​

migrate 命令旨在快速将现有项目迁移到 Vite+。以下是该命令执行的操作：

  • 更新项目依赖
  • 在需要时重写导入
  • 将特定工具的配置合并到 vite.config.ts
  • 将脚本更新为 Vite+ 命令集
  • 可以设置提交钩子
  • 可以写入代理和编辑器配置文件
  • 格式化已迁移的项目

有关确切的依赖、源代码重写和包管理器行为，请参见 迁移规则。

大多数项目在运行 vp migrate 后仍需要进一步手动调整。

推荐工作流程 ​

运行迁移之前：

  • 升级到 Vite 8+ 和 Vitest 4.1+
  • 确保了解任何应予以保留的现有 lint、格式化或测试配置

运行迁移之后：

  • 运行 vp install
  • 运行 vp check
  • 运行 vp test
  • 运行 vp build（如果您要构建库，则运行 vp pack）

迁移提示 ​

如果您想将此工作交给编码代理（或阅读者是编码代理！），请使用以下迁移提示：

md
将此项目迁移到 Vite+。Vite+ 取代了围绕运行时管理、包管理、开发/构建/测试命令、代码检查、格式化和打包的当前拆分工具链。运行 `vp help` 了解 Vite+ 的能力，并在修改前运行 `vp help migrate`。在工作区根目录使用 `vp migrate --no-interactive`。确保项目在迁移前使用 Vite 8+ 和 Vitest 4.1+。

迁移完成后：

- Confirm `vite` imports were rewritten to `vite-plus` where needed
- Confirm `vitest` imports were rewritten to `vite-plus/test` (and `@vitest/browser*` to `vite-plus/test/browser*`) where needed
- On pnpm, keep the `vite`, `vitest` dependency entries configured by `vp migrate` so the workspace aliases and overrides stay effective; with other package managers, you can remove them once those rewrites are confirmed
- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`

命令映射（需牢记）：

- `vp run <script>` 等价于 `pnpm run <script>`
- `vp dev` 和 `vp test` 始终运行内置命令；`vp run dev` 和 `vp run test` 运行 `package.json` 中的 `dev` 和 `test` 脚本
- `vp install`、`vp add` 和 `vp remove` 通过 `packageManager` 声明的包管理器执行
- `vp dev`、`vp build`、`vp preview`、`vp lint`、`vp fmt`、`vp check` 和 `vp pack` 取代相应的独立工具
- 优先使用 `vp check` 进行验证循环

最后，通过运行以下命令验证迁移：`vp install`、`vp check`、`vp test` 和 `vp build`

最后总结迁移并报告仍需手动跟进的事项。

特定工具迁移 ​

Vitest ​

Vitest 会通过 vp migrate 自动迁移。vite-plus 会将上游 [email protected] 以 vite-plus/test* 的形式重新导出，因此对于 node 模式测试，只需安装一次 vite-plus 即可——您不再需要直接安装 vitest。

浏览器模式则更复杂一些。vite-plus 捆绑了基础浏览器运行时（@vitest/browser）和预览提供程序（@vitest/browser-preview），但 Playwright 和 WebdriverIO 提供程序仍需按需启用：@vitest/browser-playwright（及其 playwright peer）和 @vitest/browser-webdriverio（及其 webdriverio peer）不会随 vite-plus 一同提供，因此非浏览器项目不会拉取它们。vp migrate 会检测您实际使用的提供程序并将其添加进去——固定到捆绑的 vitest 版本——以及其对应框架。如果您手动迁移并使用其中一种提供程序，请自行安装该提供程序包及其框架，以便 vite-plus/test/browser-playwright / vite-plus/test/browser-webdriverio 能够解析。

如果您是手动迁移，请改为将所有导入更新为 vite-plus/test*：

ts
// 之前
import { defineConfig } from 'vitest/config';
import { describe, expect, it, vi } from 'vitest';
import { playwright } from '@vitest/browser-playwright';

const { page } = await import('@vitest/browser/context');

// 之后
import { defineConfig } from 'vite-plus';
import { describe, expect, it, vi } from 'vite-plus/test';
import { playwright } from 'vite-plus/test/browser-playwright';

const { page } = await import('vite-plus/test/browser/context');

declare module 'vitest' / declare module '@vitest/browser*' 的模块增强不会被刻意重写——vite-plus/test* 只是上游 vitest* 的薄封装重新导出，因此类型增强必须指向上游模块标识才能正确合并。请保留这些 declare module 语句指向 'vitest' / '@vitest/browser*'。

tsdown ​

如果项目使用 tsdown.config.ts，将其选项移动到 vite.config.ts 的 pack 块中：

tsdown.config.ts
ts
import { defineConfig } from 'tsdown';

export default defineConfig({
  entry: ['src/index.ts'],
  dts: true,
  format: ['esm', 'cjs'],
});
vite.config.ts
ts
import { defineConfig } from 'vite-plus';

export default defineConfig({
  pack: {
    entry: ['src/index.ts'],
    dts: true,
    format: ['esm', 'cjs'],
  },
});

合并后删除 tsdown.config.ts。有关完整配置参考，请参见 打包指南。

lint-staged ​

Vite+ 用其自身的 staged 块（在 vite.config.ts 中）取代了 lint-staged。仅支持 staged 配置格式。独立的非 JSON 格式 .lintstagedrc 和 lint-staged.config.* 不会被自动迁移。

将您的 lint-staged 规则移动到 staged 块中：

vite.config.ts
ts
import { defineConfig } from 'vite-plus';

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

当没有现有的钩子策略负责此工作流时，vp migrate 可以迁移受支持的 lint-staged 规则，并删除旧配置和依赖。如果保留了现有的钩子工具，请继续保留 lint-staged，直到您手动转换该钩子策略。有关详情，请参见提交钩子指南和Staged 配置参考。

Git 钩子工具 ​

vp migrate 命令不会自动转换 Husky 设置。检测到 Husky 时，Vite+ 会保留其钩子、生命周期脚本、配置和依赖不变，并显示警告。您可以使用提交钩子指南手动迁移项目。

项目现有的 Vite+ 钩子也会被保留。仅当未找到现有钩子策略时，才会引入默认的 staged 工作流。

如果您的项目当前使用 lefthook、simple-git-hooks 或 yorkie，vp migrate 会保留您现有的配置不变并显示警告。即使您选择在提示过程中设置钩子，或包含 --hooks 标志，也会如此。

如果您希望将其中一种工具手动迁移到 Vite+，可以按照以下步骤操作。首先，将暂存文件命令移动到 vite.config.ts 中的 staged 块。然后，更新您的生命周期脚本，使其运行 vp config。您还需要在 .vite-hooks/pre-commit 创建一个运行 vp staged 的 Vite+ 钩子。运行 vp hooks enable（或 vp config）以安装调度器并设置 core.hooksPath。最后，在确认 Vite+ 钩子按预期工作后，即可移除旧工具的配置和依赖。

使用 vp hooks status 验证调度器是否处于活动状态；如果需要在此克隆中再次将其关闭，请使用 vp hooks disable。有关完整 Vite+ 钩子设置的更多详情，请参见提交钩子指南。

示例 ​

bash
# 迁移当前项目
vp migrate

# 迁移指定目录
vp migrate my-app

# 以无提示模式运行
vp migrate --no-interactive

# 在迁移期间写入代理和编辑器设置
vp migrate --agent claude --editor zed

© 2026 VoidZero Inc. and Vite+ contributors.