GitHub 加速计划故障解决指南：从入门到精通

问题速查表

错误类型	解决方案
启动失败	检查 Node.js 版本 ≥18.10.0
端口占用	使用 mintlify dev --port 3333 或关闭占用进程
版本不匹配	执行 npm i -g mintlify@latest 升级 CLI
部署失败	安装 Mintlify GitHub App 并检查授权
配置损坏	删除 ~/.mintlify 目录后重新初始化

开发环境启动失败

问题场景

执行 mintlify dev 命令后，终端显示启动失败并退出，无任何预览页面打开。

排查流程

1. 🔍 检查 Node.js 版本（CLI：命令行界面工具）

   node -v
   # 预期输出示例：v18.10.0 或更高版本
   

2. 🔍 验证 Mintlify CLI 安装状态

   mintlify --version
   # 预期输出示例：mintlify/1.0.0 linux-x64 node-v18.10.0
   

解决方案

⚙️ 升级 Node.js 至 18.10.0 或更高版本：

# 使用 nvm 安装（Linux/macOS）
nvm install 18.10.0
nvm use 18.10.0

# 验证安装结果
node -v
# 应显示 v18.10.0 或更高版本

验证标准

✅ 成功启动开发服务器：

mintlify dev
# 预期输出包含 "Server running at http://localhost:3000"

预防措施

[!WARNING] 避免使用 Node.js 19.x 版本，可能存在兼容性问题。建议使用 LTS 版本（18.x 或 20.x）。

开发服务器端口冲突

问题场景

启动开发服务器时显示 Error: listen EADDRINUSE: address already in use :::3000 错误信息。

排查流程

1. 🔍 查找占用 3000 端口的进程：

   # Linux/macOS
   lsof -i :3000
   
   # Windows (PowerShell)
   netstat -ano | findstr :3000
   

解决方案

⚙️ 方案一：使用自定义端口启动

mintlify dev --port 3333
# 预期输出：Server running at http://localhost:3333

⚙️ 方案二：终止占用进程（Linux/macOS）

# 替换 PID 为实际进程 ID
kill -9 PID

验证标准

✅ 确认服务器在指定端口正常运行：

curl http://localhost:3333/health
# 预期输出：OK

预防措施

在 package.json 中添加启动脚本：

"scripts": {
  "dev": "mintlify dev --port 3333"
}

部署验证失败

问题场景

代码推送后，GitHub 仓库未显示部署成功标识，文档未更新。

排查流程

1. 🔍 检查 Mintlify GitHub App 安装状态：
   • 登录 Mintlify 控制台
   • 确认目标仓库旁显示绿色 check 标记

解决方案

⚙️ 手动部署流程：

1. 确保代码已推送到主分支
2. 登录 Mintlify 控制台
3. 找到对应仓库，点击"Manual Deploy"按钮

验证标准

✅ 部署成功后，GitHub 提交记录旁会显示验证状态：

预防措施

[!WARNING] 确保仓库主分支名称为 main 或 master，其他分支不会自动触发部署。

常见问题关联图

graph TD
    A[开发环境问题] -->|导致| B[启动失败]
    A -->|导致| C[端口冲突]
    D[部署问题] -->|导致| E[验证失败]
    F[配置问题] -->|导致| B
    F -->|导致| E
    B --> G[Node.js 版本过低]
    C --> H[3000端口被占用]
    E --> I[GitHub App 未安装]

附录：高级故障处理

配置文件损坏

当出现加载失败时，执行以下命令重置配置：

# Linux/macOS
rm -rf ~/.mintlify
mintlify dev

# Windows
rd /s /q %USERPROFILE%\.mintlify
mintlify dev

Windows 路径错误

重建核心文件：

# 在 Git Bash 中执行
cd ~/.mintlify
rm -rf mint
git clone https://gitcode.com/gh_mirrors/star/starter

完整文档请参考项目内 development.mdx 和 quickstart.mdx 文件。