在 GitHub Codespaces 中解决 Vercel + Astro 部署的 pnpm 锁文件报错

在使用 Vercel 部署基于 Astro 构建的博客（如 Firefly 主题）时，我们常常需要接入诸如 @vercel/analytics 这样强大的访问统计工具。

如果你手头没有本地开发环境，想直接在 GitHub 网页端搞定这一切，可能会遇到一些小坑。本文将带你从零开始，完整走通“注入统计代码 -> 触发云端报错 -> 使用 GitHub Codespaces 优雅解决”的全过程。

第一步：在 GitHub 网页端修改布局文件#

通常像 Astro 主题都会有一个全局的布局组件。我们可以直接在 GitHub 网页端找到它并植入统计代码。

打开你的 GitHub 项目仓库。
导航找到布局文件，路径通常是 src/layouts/Layout.astro（或者 BaseLayout.astro）。
点击文件右上角的 铅笔图标（Edit file） 开始在线编辑。

1. 顶部导入 Analytics 组件#

在文件最顶部的 Frontmatter 区域（前后都有 --- 的地方），加入导入语句：

1
---
2
// 其他已有的 import 语句...
3
import Analytics from '@vercel/analytics/astro';
4

5
// 接收的 Props 或其他代码...
6
---

2. 在 body 标签内部插入组件#

在 HTML 的 <body> 标签内部（建议放在页面的最底部、闭合标签 </body> 的上方），加入组件代码：

代码段

1
    <body>
2
      <!-- 页面主体内容 -->
3
      <slot />
4

5
      <!-- 插入 Vercel Analytics -->
6
      <Analytics/>
7
    </body>
8
  </html>

修改完成后，点击右上角的 Commit changes… 提交保存。

第二步：Vercel 部署报错：pnpm 锁文件冲突#

当你把代码提交到 GitHub 之后，Vercel 会自动触发重新部署。但如果你之前项目里没有安装过这个依赖，构建日志里大概率会抛出这样一个让人头疼的错误：

Plaintext

1
[ERR_PNPM_OUTDATED_LOCKFILE] Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json
2
Error: [BUILD_UTILS_SPAWN_1] Command "pnpm install" exited with 1

这是因为项目使用的是 pnpm，而 Vercel 在云端构建时默认开启了严格的锁文件检查（Frozen Lockfile）。因为你在代码里用了新依赖，但没有本地电脑去运行 pnpm install 更新 pnpm-lock.yaml，导致两边对不上，构建直接中断。

没有本地电脑，怎么更新锁文件呢？别慌，我们有终极武器——GitHub Codespaces。

第三步：使用 GitHub Codespaces 妙解锁文件冲突#

GitHub 官方自带的云端开发环境（Codespaces）可以让我们直接在浏览器里拥有一个完整的 Linux 终端。

1. 召唤云端编辑器#

在你的 GitHub 项目仓库主页面，直接在键盘上按下英文句号键 .（点号）。
稍等几秒钟，页面就会神奇地变成一个网页版的 VS Code。

2. 在云端运行安装命令#

在页面下方自带的终端（Terminal）面板中，直接输入并回车：

Bash

1
pnpm install

这一步会让 pnpm 在云端自动帮你把依赖补全，并完美更新根目录下的 pnpm-lock.yaml 文件。

3. 提交并推送更改#

点击左侧边栏的源代码管理图标（分支图标）。
你会看到被自动更新的 pnpm-lock.yaml 和 package.json 文件。
在上方输入框写下提交信息，例如：fix: update pnpm-lock.yaml for vercel analytics。
点击 Commit，然后点击 Push 将代码推送到远程 GitHub 仓库。

🎉 大功告成#

完成推送后，你可以直接关掉 Codespaces 标签页。

回到你的 Vercel 控制台，你会发现项目已经自动触发了新的一次部署。这一次，由于 pnpm-lock.yaml 已经和代码完全同步，Vercel 顺利通过了严格锁文件检查，项目完美构建成功！

小结：善用 GitHub 网页端与 Codespaces 的组合，即使身边的电脑没有配开发环境，也能随时随地轻松搞定静态站点的各类维护与部署难题。

音乐