解决 Cloudflare Pages 部署 VitePress 时最后更新时间异常问题

🚨 问题描述

VitePress 提供了一个非常实用的功能——自动显示每个页面的最后更新时间。这个功能基于 Git 提交历史，可以帮助读者了解内容的时效性。

然而，当我们将 VitePress 博客部署到 Cloudflare Pages 时，可能会遇到一个奇怪的问题：所有页面都显示相同的最后更新时间。

这个问题不仅影响了用户体验，也让读者无法准确判断各篇文章的更新状态。

🔍 问题分析

Cloudflare Pages 的 Git 克隆机制

Cloudflare Pages 在构建项目时，默认使用的是 浅克隆（Shallow Clone） 方式来获取 Git 仓库。这意味着：

• 只会下载最新的一次提交记录
• 无法获取完整的历史提交信息
• 所有文件的最后修改时间都会被标记为同一个时间点

对 VitePress 的影响

VitePress 的 lastUpdated 功能依赖于 Git 历史记录来获取每个文件的实际修改时间。当使用浅克隆时：

<script setup>
// VitePress 获取最后更新时间组件（简化逻辑）
import { computed } from 'vue';
import { useData } from 'vitepress';

const { page } = useData();
const lastUpdated = computed(() => new Date(page.value.lastUpdated));
</script>

由于所有文件都只有同一个提交时间戳，因此所有页面都会显示相同的更新时间。

💡 解决方案

核心思路：获取完整的 Git 历史

解决这个问题的关键是在构建前获取完整的 Git 历史记录。我们可以使用 Git 的 --unshallow 参数来将浅克隆转换为完整克隆。

git fetch --unshallow

这个命令会：

• 下载完整的 Git 历史记录
• 保留所有分支和标签信息
• 获取每个文件的真实修改时间

🔧 实施步骤

1. 修改 package.json 添加 git:fetch 脚本

在 package.json 的 scripts 部分添加 git:fetch 命令：

{
  "scripts": {
    "docs:dev": "vitepress dev src",
    "docs:build": "vitepress build src",
    "docs:preview": "vitepress preview src",
    "git:fetch": "git fetch --unshallow"
  }
}

2. 修改 Cloudflare Pages 构建命令

在 Cloudflare Pages 的设置中，将构建命令修改为：

yarn install && yarn docs:build
yarn git:fetch && yarn install && yarn docs:build

这个命令的执行顺序：

1. yarn git:fetch - 获取完整的 Git 历史
2. yarn install - 安装项目依赖
3. yarn docs:build - 构建文档

3. 配置 Cloudflare Pages

1. 登录 Cloudflare Dashboard
2. 进入 Pages 项目设置
3. 找到 Builds & deployments → Build configuration
4. 修改 Build command 为上述命令
5. 保存设置并重新部署

✅ 效果验证

部署完成后，可以通过以下方式验证问题是否解决：

1. 检查页面显示

访问你的博客网站，查看不同文章的最后更新时间是否：

• 显示了不同的更新时间
• 时间戳与实际的文件修改时间相符
• 符合预期的显示格式

2. 查看构建日志

在 Cloudflare Pages 的构建日志中，你应该能看到类似的输出：

Executing user command: yarn git:fetch && yarn install && yarn docs:build
yarn run v1.22.22
$ git fetch --unshallow // [!code focus:4]
From https://github.com/xxxx/xxxx-doc
 * [new branch]      main       -> origin/main
Done in 0.65s.
yarn install v1.22.22
[1/5] Validating package.json...
[2/5] Resolving packages...
success Already up-to-date.
Done in 0.10s.
$ vitepress build

🚀 GitHub Actions

如果你使用 GitHub Actions 或其他 CI/CD 工具，也可以在构建脚本中添加类似的步骤：

# GitHub Actions 示例
build:
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

📊 解决前后对比

方面	解决前	解决后
更新时间显示	所有页面显示相同时间	每个页面显示真实的最后修改时间
用户体验	读者无法判断内容时效性	读者可以准确了解文章更新状态
Git 历史	只有最近一次提交	完整的提交历史
构建时间	稍快（克隆历史少）	稍慢（需要下载完整历史）

📝 总结

通过添加 git fetch --unshallow 命令到构建流程中，我们成功解决了 Cloudflare Pages 部署 VitePress 时最后更新时间异常的问题。

关键要点：

• ✅ 问题根源是 Cloudflare Pages 的浅克隆机制
• ✅ 使用 git fetch --unshallow 获取完整 Git 历史
• ✅ 修改构建命令确保在安装依赖前执行 git:fetch
• ✅ 验证各页面显示正确的更新时间

这个解决方案不仅解决了当前问题，也为其他依赖 Git 历史的静态网站生成器提供了参考思路。通过简单的配置调整，我们就能在享受 Cloudflare Pages 带来的便利的同时，保持网站功能的完整性。