跳到主要内容

故障排除

本文档收录常见问题及其解决方案。

安装问题​

npm 安装失败​

问题：执行 npm install 时报错

解决方案：

# 清除缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install

权限错误（EACCES）​

问题：macOS/Linux 上遇到权限错误

解决方案：

# 使用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

构建问题​

构建失败​

问题：npm run build 失败

解决方案：

  1. 检查 Node.js 版本：
node --version  # 应该是 20.x
  1. 确保所有依赖正确安装：
npm install
  1. 清理构建缓存：
npm run clear
npm run build

内存不足​

问题：构建时内存溢出

解决方案：

NODE_OPTIONS="--max-old-space-size=4096" npm run build

运行时问题​

页面 404​

问题：刷新页面后出现 404

解决方案：

确保服务器配置了 SPA 回退，所有路径都返回 index.html。

中文路由不工作​

问题：/zh/docs/... 路径无法访问

解决方案：

检查 docusaurus.config.ts 中的 trailingSlash 设置：

{
  trailingSlash: false,
}

API 问题​

API 认证失败​

问题：收到 401 未授权错误

解决方案：

  1. 确认 API 密钥正确
  2. 检查是否过期
  3. 确认请求 Header 格式：
Authorization: Bearer YOUR_API_KEY

请求超时​

问题：API 请求超时

解决方案：

const client = new OpenHuman({
  apiKey: process.env.OPENHUMAN_API_KEY,
  timeout: 120000, // 增加到 120 秒
});

速率限制​

问题：收到 429 错误

解决方案：

  • 等待一段时间后重试
  • 实现请求队列
  • 考虑升级套餐

部署问题​

Cloudflare Pages 部署失败​

解决方案：

  1. 检查 GitHub 仓库连接状态
  2. 验证构建日志
  3. 确认 wrangler.toml 配置正确
  4. 尝试手动重新部署

域名解析失败​

解决方案：

  1. 确认 DNS 记录正确添加
  2. 等待 DNS 传播（最长 48 小时）
  3. 使用 dig 或 nslookup 检查解析

开发问题​

热更新不工作​

问题：修改文件后浏览器没更新

解决方案：

# 停止开发服务器
# 清除缓存
npm run clear

# 重新启动
npm start

CSS 样式不生效​

问题：修改 CSS 后样式没变化

解决方案：

  1. 清除浏览器缓存
  2. 禁用 CSS 压缩（开发模式）
  3. 检查 CSS 文件是否正确导入

性能问题​

首屏加载慢​

解决方案：

  1. 启用 gzip 压缩
  2. 优化图片资源
  3. 使用 CDN
  4. 检查是否有大文件未分割

搜索不工作​

解决方案：

  1. 确认已配置 Algolia DocSearch
  2. 检查 algolia 配置正确
  3. 确认爬虫已运行并建立索引

获取帮助​

如果问题仍未解决：