部署故障排除指南

本文档记录了项目部署过程中遇到的常见问题和解决方案，特别是针对 Cloudflare Pages 和其他静态站点部署平台的故障排除经验。

📋 目录

Cloudflare Pages 部署问题
Node.js 包管理器问题
VitePress 构建问题
最佳实践建议

🌐 Cloudflare Pages 部署问题

问题 1: Yarn Lockfile 版本冲突

错误表现

➤ YN0087: Migrated your project to the latest Yarn version 🚀
➤ YN0000: · Yarn 4.9.1
➤ YN0028: │ The lockfile would have been modified by this install, which is explicitly forbidden.
➤ YN0000: └ Failed with errors in 4s 329ms
Error: Exit with error code: 1

问题原因

版本不匹配: 本地使用 Yarn 1.x，Cloudflare Pages 检测到并自动升级到 Yarn 4.x
Lockfile 格式冲突: Yarn 1.x 的 yarn.lock 格式与 Yarn 4.x 不兼容
packageManager 字段强制: package.json 中的 "packageManager": "yarn@4.9.2" 强制使用特定版本

完整解决方案

步骤 1: 检查项目配置

bash

# 检查当前包管理器设置
cat package.json | grep -A 2 -B 2 "packageManager"

# 检查脚本命令
cat package.json | grep -A 5 "scripts"

步骤 2: 修改 package.json

json

{
  "scripts": {
    "semantic-release": "semantic-release",
    "docs:dev": "npx vitepress dev docs",
    "docs:build": "npx vitepress build docs", 
    "docs:preview": "npx vitepress preview docs"
  },
  "engines": {
    "node": ">=18"
  }
  // 删除 "packageManager" 字段
}

步骤 3: 清理 lockfile

bash

# 删除现有的 lockfile
rm yarn.lock

# 从 git 中移除
git rm yarn.lock

# 让部署平台自行生成合适的 lockfile

步骤 4: 提交更改

bash

git add package.json
git commit -m "🔧 fix(build): 修复 Cloudflare Pages 部署问题

- 移除 packageManager 字段，让构建系统自行选择包管理器
- 将脚本命令从 yarn 改为 npx，提供更好的兼容性
- 移除 yarn.lock，让部署平台生成适合的 lockfile"

git push

原理解释

移除 packageManager 限制:
- 删除 "packageManager" 字段让部署平台使用默认配置
- Cloudflare Pages 可以选择最适合的包管理器版本
使用 npx 替代 yarn:
- npx 是 Node.js 包执行器，与包管理器无关
- 可以运行任何已安装的包，无论是通过 npm、yarn 还是 pnpm 安装
移除 lockfile 冲突:
- 让部署平台根据其选择的包管理器生成相应的 lockfile
- 避免版本格式不匹配问题

问题 2: Node.js 版本不兼容

错误表现

Error: This package requires Node.js >=18
Current Node.js version: 16.x.x

解决方案

在 package.json 中明确指定 Node.js 版本要求：

json

{
  "engines": {
    "node": ">=18"
  }
}

📦 Node.js 包管理器问题

包管理器选择策略

开发环境灵活性

项目支持多种包管理器，开发者可以根据偏好选择：

bash

# 使用 npm
npm install
npm run docs:dev

# 使用 yarn
yarn install
yarn docs:dev

# 使用 pnpm
pnpm install
pnpm docs:dev

部署环境兼容性

通过使用 npx 命令确保部署环境兼容性：

json

{
  "scripts": {
    "docs:build": "npx vitepress build docs"
  }
}

这样无论部署平台使用哪种包管理器，都能正确执行构建命令。

Lockfile 管理策略

本地开发

建议开发者在本地保持 lockfile 来确保依赖版本一致性
可以使用 .gitignore 忽略 lockfile 以避免版本冲突

生产部署

让部署平台自行生成适合的 lockfile
通过 package.json 的版本范围控制依赖稳定性

📖 VitePress 构建问题

常见构建错误

问题: 内存不足

Error: Process out of memory

解决方案: 在构建脚本中增加内存限制

json

{
  "scripts": {
    "docs:build": "NODE_OPTIONS=--max-old-space-size=4096 npx vitepress build docs"
  }
}

问题: 静态资源路径

Error: Failed to resolve import "./assets/image.png"

解决方案: 使用相对路径或 VitePress 的 public 目录

markdown

<!-- 正确的图片引用 -->
![描述](/images/screenshot.png)

<!-- 或使用相对路径 -->
![描述](../assets/image.png)

🚀 最佳实践建议

1. 包管理器配置最佳实践

✅ 推荐配置

json

{
  "scripts": {
    "docs:dev": "npx vitepress dev docs",
    "docs:build": "npx vitepress build docs",
    "docs:preview": "npx vitepress preview docs"
  },
  "engines": {
    "node": ">=18"
  }
}

❌ 避免的配置

json

{
  "scripts": {
    "docs:build": "yarn vitepress build docs"  // 硬编码包管理器
  },
  "packageManager": "yarn@4.9.2"  // 强制特定版本
}

2. 部署环境配置

Cloudflare Pages 推荐设置

构建命令: npm run docs:build
输出目录: docs/.vitepress/dist
Node.js 版本: 18 或更高
环境变量: 根据需要设置

兼容性检查清单

[ ] package.json 中没有 packageManager 字段
[ ] 脚本使用 npx 而不是特定包管理器
[ ] 没有提交 lockfile 或使用通用格式
[ ] Node.js 版本要求明确指定
[ ] 依赖版本使用合理的范围约束

3. 故障排除流程

部署失败时的诊断步骤

检查构建日志: 查看具体的错误信息
验证本地构建: 在本地运行 npm run docs:build
检查依赖兼容性: 确保所有依赖都支持目标 Node.js 版本
测试不同包管理器: 尝试使用 npm/yarn/pnpm 分别构建
查看平台文档: 参考部署平台的官方故障排除指南

本地验证脚本

bash

#!/bin/bash
# scripts/validate-deployment.sh

echo "🔍 验证部署配置..."

# 检查 Node.js 版本
echo "Node.js 版本: $(node --version)"

# 检查包管理器配置
echo "📦 检查 package.json 配置..."
if grep -q "packageManager" package.json; then
    echo "⚠️  警告: 发现 packageManager 字段，可能导致部署冲突"
fi

# 测试构建命令
echo "🏗️  测试文档构建..."
npm install
npm run docs:build

echo "✅ 验证完成"

📚 相关资源

官方文档

项目文档

工具和命令

bash

# 包管理器诊断
npm doctor
yarn doctor

# 构建环境检查
npx envinfo --system --npmPackages --binaries

# VitePress 调试
npx vitepress build docs --debug

📝 更新记录

日期	问题	解决方案	关联 PR
2025-06-20	Yarn lockfile 版本冲突导致 Cloudflare Pages 部署失败	移除 packageManager 字段，使用 npx 命令，删除 lockfile	#9

本文档会持续更新，记录新发现的部署问题和解决方案。

部署故障排除指南 ​

📋 目录 ​

🌐 Cloudflare Pages 部署问题 ​

问题 1: Yarn Lockfile 版本冲突 ​

错误表现 ​

问题原因 ​

完整解决方案 ​

原理解释 ​

问题 2: Node.js 版本不兼容 ​

错误表现 ​

解决方案 ​

📦 Node.js 包管理器问题 ​

包管理器选择策略 ​

开发环境灵活性 ​

部署环境兼容性 ​

Lockfile 管理策略 ​

本地开发 ​

生产部署 ​

📖 VitePress 构建问题 ​

常见构建错误 ​

问题: 内存不足 ​

问题: 静态资源路径 ​

🚀 最佳实践建议 ​

1. 包管理器配置最佳实践 ​

✅ 推荐配置 ​

❌ 避免的配置 ​

2. 部署环境配置 ​

Cloudflare Pages 推荐设置 ​

兼容性检查清单 ​

3. 故障排除流程 ​

部署失败时的诊断步骤 ​

本地验证脚本 ​

📚 相关资源 ​

官方文档 ​

项目文档 ​

工具和命令 ​

📝 更新记录 ​

部署故障排除指南

📋 目录

🌐 Cloudflare Pages 部署问题

问题 1: Yarn Lockfile 版本冲突

错误表现

问题原因

完整解决方案

原理解释

问题 2: Node.js 版本不兼容

错误表现

解决方案

📦 Node.js 包管理器问题

包管理器选择策略

开发环境灵活性

部署环境兼容性

Lockfile 管理策略

本地开发

生产部署

📖 VitePress 构建问题

常见构建错误

问题: 内存不足

问题: 静态资源路径

🚀 最佳实践建议

1. 包管理器配置最佳实践

✅ 推荐配置

❌ 避免的配置

2. 部署环境配置

Cloudflare Pages 推荐设置

兼容性检查清单

3. 故障排除流程

部署失败时的诊断步骤

本地验证脚本

📚 相关资源

官方文档

项目文档

工具和命令

📝 更新记录