Vite+

故障排除 ​

当 Vite+ 的行为不符合预期时，请使用本页面。

INFO

Vite+ 1.0 已发布。我们会持续改进，并欢迎社区反馈。如果有任何内容未按预期工作，请联系我们。

支持的工具版本 ​

自动迁移对现有 Vite 和 Vitest 依赖项要求以下最低版本：

  • Vite 7 或更高版本
  • Vitest 4 或更高版本

如果你正在迁移一个现有项目，并且它仍然依赖旧版本的 Vite 或 Vitest，请先升级这些依赖，然后再采用 Vite+。

运行 vp toolchain 可显示本地 Vite+ 软件包中的版本。运行 vp toolchain --global 可显示全局 Vite+ 版本中的版本。

vp check 不会运行类型感知 lint 规则或类型检查 ​

  • 确认 vite.config.ts 中已启用 lint.options.typeAware 和 lint.options.typeCheck
  • 检查你的 tsconfig.json 是否仍在使用 compilerOptions.baseUrl

由 tsgolint 驱动的 Oxlint 类型检查器路径不支持 baseUrl。vp migrate 和 vp lint --init 会尝试在启用类型感知 lint 之前运行 vp dlx @andrewbranch/ts5to6 --fixBaseUrl <tsconfig path> 修复。如果该修复失败或被拒绝，Vite+ 会跳过 typeAware 和 typeCheck。

嵌套 lint 或格式配置未生效 ​

运行 vp lint、vp fmt 或 vp check 时，子目录中的配置不会覆盖单个文件的设置。vp lint 和 vp fmt 会从工作目录开始让 Oxlint 和 Oxfmt 查找配置，因此从包目录运行时，包配置中的 lint 或 fmt 块会生效；但我们不建议这样做。如果存在工作区根目录的 lint 和 fmt 块，vp check 会选用它们。使用 vp lint 或 vp fmt 时，可通过 -c <path> 或 --config <path> 显式选择其他配置。

将 lint 和格式设置保存在根目录的 vite.config.ts 中。使用 lint.overrides 和 fmt.overrides 为特定文件或软件包设置专属配置。你还可以将配置对象导入根配置，以便将设置保存在单独的文件中。

将编辑器的 lint 和格式化配置为使用工作区根目录的 vite.config.ts。有关特定编辑器的设置说明，请参阅 IDE 集成。

目前我们暂不将嵌套配置应用于单个文件。我们正在考虑的因素包括：隐式配置发现如何影响 lint 和格式化的可预测性、AI 代理需要哪些上下文才能理解适用的设置，以及查找和加载多个配置可能带来的性能成本。同时，我们也认识到，将包特定的上下文保留在代码附近可能有好处。到目前为止，我们听到的用例还不足以让我们确定采用这些语义。暂缓支持为日后添加该功能留出了空间；我们也希望了解你的项目为何需要嵌套配置，尤其是在根级覆盖无法满足需求时。

你需要嵌套配置吗？在 GitHub 上分享你的用例和意见，包括你的项目结构、想要使用嵌套配置的原因，以及根级覆盖是否能满足你的需求。

我们非常希望听到你的反馈。这将帮助我们决定未来是否改进当前情况。

VS Code 扩展未读取 vite.config.ts ​

如果 VS Code 同时打开了多个文件夹，共享的 Oxc 语言服务器可能会选择与预期不同的工作区。这可能导致看起来像是缺少 vite.config.ts 支持。

  • 确认扩展正在使用正确的工作区。

vp dev 或 vp build 不会运行我的脚本 ​

与包管理器不同，内置命令无法被覆盖。如果你想运行 package.json 脚本，请改用 vp run <script>。

例如：

  • vp dev 始终启动内置的 Vite 开发服务器
  • vp build 始终运行内置的 Vite 构建命令
  • vp test 始终运行内置的 Vitest 命令
  • vp run dev、vp run build 和 vp run test 会运行相应的 package.json 脚本

关于何时优先选择这两种方式，请参阅内置命令与脚本。

INFO

你还可以在 vite.config.ts 中定义自定义任务，并完全迁移出 package.json 脚本。

分阶段检查与提交钩子 ​

如果 vp staged 失败或预提交钩子未运行：

  • 确保 vite.config.ts 包含 staged 配置块
  • 确保项目自有的预提交钩子运行 vp staged（例如 .vite-hooks/pre-commit）
  • 运行 vp hooks status 查看偏好设置、core.hooksPath 以及调度器是否已安装
  • 运行 vp hooks enable（或 vp config）以安装钩子调度器
  • 如果状态显示 Preference: disabled (local)，请使用 vp hooks enable 重新启用
  • 检查是否通过 VP_GIT_HOOKS=0 有意跳过了钩子

要在此克隆版本中停止钩子而不删除项目策略文件，请运行 vp hooks disable。有关完整工作流程，请参阅提交钩子指南。

一个最小的分阶段配置示例如下：

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

export default defineConfig({
  staged: {
    '*': 'vp check --fix',
  },
});

由于重型插件导致的配置加载缓慢 ​

当 vite.config.ts 在顶层导入插件时，这些插件会在每次执行命令时被求值，包括 vp lint、vp fmt、编辑器集成以及长生命周期的后台进程。这会使配置加载变慢，并可能触发插件初始化的副作用，例如读取文件、启动监听器或连接到服务。

使用 lazyPlugins 可在 vite-plus 仅为读取元数据而加载你的配置时跳过插件工厂（lint、fmt、check、staged、pack、create、run/cache 任务查找，以及编辑器工具）。当 Vite 真正运行时，插件仍会加载：dev、build、test、preview，以及你的脚本所启动的任何构建（例如 vp run 任务、vp exec）：

vite.config.ts
ts
import myPlugin from 'vite-plugin-foo';
import { defineConfig, lazyPlugins } from 'vite-plus';

export default defineConfig({
  plugins: lazyPlugins(() => [myPlugin()]),
});

对于应当延迟导入的重型插件，将其与动态 import() 结合使用：

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

export default defineConfig({
  plugins: lazyPlugins(async () => {
    const { default: heavyPlugin } = await import('vite-plugin-heavy');
    return [heavyPlugin()];
  }),
});

请在回调函数内部直接导入插件软件包。对本地模块使用动态 import()（例如 await import('./vite.plugins.ts')）并不能避免开销：Vite 会在加载配置前先打包配置，并跟踪对本地文件的动态导入，因此即使回调从未运行，该模块及其导入的软件包仍会在每条命令中被处理。

寻求帮助 ​

如果你遇到困难，请联系我们：

  • Discord 用于实时讨论和故障排除帮助
  • GitHub 用于问题、讨论和错误报告

在报告问题时，请包含：

  • vp env current、vp --version 和 vp toolchain 的完整输出
  • 项目使用的软件包管理器
  • 重现问题所需的准确步骤以及你的 vite.config.ts
  • 最小复现仓库或可运行的沙盒。

© 2026 VoidZero Inc. and Vite+ contributors.