Vite+

故障排除 ​

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

INFO

Vite+ 处于 beta 阶段：稳定，但尚未完整。我们正在通往 1.0 的路上添加功能，并优先考虑社区反馈，所以如果某些内容没有按预期工作，请联系我们。

支持的工具版本 ​

Vite+ 期望使用现代的上游工具版本。

  • Vite 8 或更高版本
  • Vitest 4.1 或更高版本

如果你正在迁移一个现有项目，并且它仍然依赖旧版本的 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 . 修复。如果该修复失败或被拒绝，Vite+ 会跳过 typeAware 和 typeCheck。

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

Vite+ 目前不支持嵌套 lint 或格式配置。从工作区根目录运行 vp lint、vp fmt 或 vp check 时，不要依赖子目录中的配置，也不要依赖软件包级 vite.config.ts 文件中的 lint 和 fmt 块来覆盖根设置。

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

对于 IDE 集成，我们提供了 disableNestedConfig 和 fmt.disableNestedConfig 配置，用于禁用嵌套 lint 和格式配置，并使编辑器行为与根 Vite+ 配置保持一致。有关编辑器的设置说明，请参阅 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 { defineConfig, lazyPlugins } from 'vite-plus';
import myPlugin from 'vite-plugin-foo';

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()];
  }),
});

寻求帮助 ​

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

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

在报告问题时，请包含：

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

© 2026 VoidZero Inc. and Vite+ contributors.