Plume 构建错误排查与修复

约 649 字大约 2 分钟

2026-09-05

概述

在本地运行开发服务器或在 CI 环境（Netlify / Vercel / GitHub Actions）部署 VuePress 项目时，常遇到依赖版本不匹配或锁文件过期的错误。此类问题通常源于手动改动 package.json 后未同步锁文件，或主题对 VuePress 核心包有固定版本要求。本文整理两条典型报错链路的排查与修复方法，以及相应的版本管理建议。

一、本地运行 `npm run docs:dev` 提示依赖版本不匹配

错误现象

本地终端运行开发指令时，抛出如下警告或错误：

vuepress-theme-plume: ⚠ 以下依赖版本不匹配：

devDependencies:
  @vuepress/bundler-vite: 2.0.0-rc.31 -> 2.0.0-rc.30
  vuepress: 2.0.0-rc.31 -> 2.0.0-rc.30

请更新依赖至正确的版本。

原因分析

当前使用的主题（vuepress-theme-plume）要求固定的 VuePress 核心包版本（如 2.0.0-rc.30），而项目实际安装的是更高的版本（如 2.0.0-rc.31）。

解决方法

锁定 package.json 中的版本号

去除 @vuepress/bundler-vite 和 vuepress 版本号前面的 ^ 或 ~ 符号：

{
  "devDependencies": {
    "@vuepress/bundler-vite": "2.0.0-rc.30",
    "vuepress": "2.0.0-rc.30"
  }
}

重新安装本地依赖
使用项目对应的包管理器重新安装。
使用 pnpm：
```
pnpm install
```
使用 npm：
```
rm -rf node_modules package-lock.json
npm install
```

二、CI 构建报错 `ERR_PNPM_OUTDATED_LOCKFILE`

错误现象

推送代码后 CI 构建失败并输出：

 ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json

  Failure reason:
  specifiers in the lockfile ({"@vuepress/bundler-vite":"2.0.0-rc.31", ...})
  don't match specs in package.json ({"@vuepress/bundler-vite":"2.0.0-rc.30", ...})

原因分析

CI 环境默认开启 --frozen-lockfile（冻结锁文件模式）。修改 package.json 中的依赖版本后，若未更新或未提交最新的 pnpm-lock.yaml，CI 会检测到锁文件与配置不一致而中断构建。

解决方法

在本地重新安装依赖以更新锁文件
```
pnpm install
```

提交更新后的 package.json 与 pnpm-lock.yaml 并推送

git add package.json pnpm-lock.yaml
git commit -m "fix: update pnpm-lock.yaml after vuepress version sync"
git push

重要

CI 使用 --frozen-lockfile 时，必须把本地生成的 pnpm-lock.yaml 一起提交；只提交 package.json 而漏掉锁文件，CI 仍会失败。

三、最佳实践建议

版本锁死：使用 VuePress 2.0 预发布（RC）版本及配套主题时，建议严格锁定版本号（不写 ^ 或 ~），规避次级版本更新引入的不兼容问题。
锁文件同步：每次手动变更 package.json 后，务必在本地运行包管理器安装命令（如 pnpm install），确保锁文件更新后再提交 Git。

版权所有

许可证：署名 4.0 国际 (CC-BY-4.0)