---
url: /tool/note/gshasgik/index.md
---
## 概述

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

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

### 错误现象

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

```text
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`）。

### 解决方法

1. **锁定 `package.json` 中的版本号**

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

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

2. **重新安装本地依赖**

   使用项目对应的包管理器重新安装。

   使用 pnpm：

   ```bash
   pnpm install
   ```

   使用 npm：

   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

## 二、CI 构建报错 `ERR_PNPM_OUTDATED_LOCKFILE`

### 错误现象

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

```text
 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 会检测到锁文件与配置不一致而中断构建。

### 解决方法

1. **在本地重新安装依赖以更新锁文件**

   ```bash
   pnpm install
   ```

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

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

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

## 三、最佳实践建议

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