CLI 问题

你存储的凭据缺失，或刷新令牌已失效。

修复： 运行 jamdesk login 开始新的会话。这将替换 ~/.jamdeskrc 中的现有内容。

如果登录后错误立即再次出现，请检查 ~/.jamdeskrc 是否已写入：

cat ~/.jamdeskrc

该文件应包含一个 auth 对象，其中有 refreshToken、email 和 uid。如果为空或缺失，你的主目录可能存在权限问题。

CLI 会在本地 9876 端口启动一个服务器，用于接收浏览器发来的认证回调。如果回调在 2 分钟内未到达，登录将超时。

常见原因：

• 防火墙阻止了本地服务器
• 在完成认证前关闭了浏览器标签页
• 9876 端口已被占用（CLI 会自动选择其他端口，但 URL 必须与之匹配）

修复： 复制终端中打印的 URL 并手动打开。检查 URL 中的端口号是否与 CLI 正在监听的端口一致。

在无头环境（SSH 会话、Docker 容器、CI 运行器）中这是正常现象。CLI 始终会将登录 URL 打印到终端。

复制该 URL，并在任意能够访问你机器回调端口的浏览器中打开。

修改 Jamdesk 密码会使所有现有的刷新令牌失效。CLI 会检测到这一点（TOKEN_EXPIRED 或 INVALID_REFRESH_TOKEN），并自动清除已存储的认证信息。

再次运行 jamdesk login。

每个项目同一时间只能运行一次构建。当构建处于排队或运行中时，CLI 会返回此错误（错误码 BUILD_IN_PROGRESS）。

修复： 等待当前构建完成。在仪表板的 Deployments 中查看状态。如果构建似乎卡住，请让项目所有者检查仪表板。

当前目录中没有 docs.json，或其中存在 JSON 语法错误。

修复：

1. 确认你位于正确的目录：ls docs.json
2. 运行 jamdesk validate 获取具体错误详情
3. 检查是否缺少逗号、括号未闭合或存在多余的逗号（CLI 对 docs.json 使用 JSON，而非 JSON5）

你压缩后的 tarball 超过了 100 MB 的限制。所有未被 .gitignore 或内置排除列表排除的文件都会被打包。

修复： 检查包含了哪些内容。常见的问题来源：视频文件、大型 PDF、未压缩的图片、数据转储文件。将它们添加到 .gitignore。

无论 .gitignore 如何设置，以下内容始终被排除：.git、node_modules、.next、.env*、*.pem、*.key、credentials.json、.DS_Store。

所有文件都匹配了排除规则。

修复： 检查你的 .gitignore 是否排除了 MDX 文件或 docs.json。

要么 docs.json 中的 projectId 与你账户中的任何项目都不匹配，要么你不是该项目的成员。

修复：

• 从 docs.json 中删除 projectId 字段，然后重新运行 jamdesk deploy 以选择新项目
• 确认你登录的是正确的账户：jamdesk whoami
• 在仪表板中检查项目成员资格

CLI 每 2 秒轮询一次构建状态。连续 3 次轮询失败后，它会放弃。

修复： 按 Ctrl+C。构建会在后台继续运行。在仪表板中查看状态。退出时 CLI 会打印一个链接。

上传成功，但构建失败。终端会显示构建服务返回的错误。

修复： 在仪表板的 Deployments 下查看构建日志。常见原因：MDX 语法错误、导航中引用的页面缺失、OpenAPI 规范无效。在本地运行 jamdesk validate 以便在部署前发现这些问题。

CLI 会对看起来像敏感信息的文件发出警告（.env、*.pem、*.key、credentials.json、以 secret 开头的文件）。该警告不会阻止部署。

修复： 将这些文件添加到 .gitignore，使其不被上传。如果它们是有意为之（例如文档中的示例密钥文件），可忽略此警告。

按顺序尝试：

1. 运行 jamdesk doctor 检查 Node.js 版本（需要 22.18+ 或 24.11+）及环境
2. 运行 jamdesk clean 清除缓存的依赖
3. 运行 jamdesk dev --verbose 查看详细错误输出
4. 运行 jamdesk dev --clean 在启动前清除构建缓存

在任何其他版本（包括 Node.js 23）上，jamdesk 会提示 "jamdesk requires Node.js 22.18+ or 24.11+" 并停止运行。请先升级 Node.js，再升级 CLI。

jamdesk dev 会使用 PATH 中第一个 node 来运行 ~/.jamdesk 下的预览。如果 Volta、asdf 或 mise 等版本管理器仅为你的项目目录固定了更新的 Node.js，预览仍会在你的默认 Node.js 上运行。jamdesk doctor 会将其报告为 "first on PATH, used by jamdesk dev"，而 jamdesk dev 会警告 "The node first on your PATH is …"。

修复： 安装受支持的 Node.js 并将其设为默认版本，而不仅仅是项目版本。使用 nvm 时，运行 nvm install 24，然后运行 nvm alias default 24（在使用 nvm-windows 的 Windows 上，运行 nvm install 24 然后运行 nvm use 24）。在主目录中打开一个新终端，并确认 node --version 显示 22.18+ 或 24.11+。

CLI 会从你请求的端口（默认 3000）开始，尝试 10 个连续的端口。如果 10 个端口全部被占用，它将失败。

修复：

# Find what's using the port
lsof -i :3000

# Pick a different port
jamdesk dev --port 3001

要设置永久的默认端口，可在 ~/.jamdeskrc 中添加 "defaultPort": 3001。不要覆盖该文件，它可能包含你的认证凭据。

在编译过程中终止开发服务器（强制退出、系统崩溃）可能会损坏 .next 缓存。下一次启动时会显示 "corrupted database" 或 panic 错误。

修复：

jamdesk dev --clean

这会清空 .next 目录并重新开始。

首次运行 jamdesk dev 时会将运行时依赖安装到 ~/.jamdesk/node_modules。这只在第一次发生，在较慢的网络下可能需要 1–2 分钟。

之后的运行会跳过安装，除非 CLI 版本发生变化。

首次运行时的 npm install 会在 5 分钟后超时。

修复：

1. 检查网络连接
2. 运行 jamdesk clean 清除未完成的安装
3. 重试
4. 如果 npm 持续缓慢，请检查 npm 注册表配置：npm config get registry

MDX 将 < 视为 JSX 标签的开始。写入 <50% 会导致解析错误。

修复： 使用 < 转义，或改写内容。运行 jamdesk validate 获取行号和建议。

jamdesk broken-links 发现了指向不存在页面的内部链接。

修复： 检查文件路径。常见错误：大小写错误（Quickstart 与 quickstart）、包含了 .mdx 扩展名，或使用了已重命名的旧路径。

对于相近的匹配（与拼写错误相差 3 个字符以内），CLI 会给出修正建议。

自动修复。 如果失效链接有明确的正确目标（拼写错误的锚点或跨语言锚点漂移），运行 jamdesk fix --dry-run 预览更改，然后运行 jamdesk fix 应用。它只会重写那些修正后的锚点确实是目标页面标题的链接。含糊的情况请手动修复。参见 自动修复失效链接。

CLI 会校验 docs.json 中引用的 OpenAPI 规范。失败原因包括无效的 $ref 引用、缺少必填字段或语法错误。

修复： 运行 jamdesk openapi-check path/to/spec.yaml 获取详细输出。对于复杂的规范，可使用 Swagger Editor 进行调试。

未全局安装，或你的 shell 找不到该可执行文件。

修复：

npm install -g jamdesk

如果你使用 curl 安装，请确保 ~/.jamdesk/bin 已加入你的 PATH。

CLI 需要对 ~/.jamdesk（缓存）和 ~/.jamdeskrc（凭据）有写入权限。

修复：

ls -la ~/.jamdesk ~/.jamdeskrc
sudo chown -R $(whoami) ~/.jamdesk ~/.jamdeskrc

jamdesk update 封装了 npm install -g jamdesk@latest。当 npm 存在权限问题或注册表无法访问时，它会失败。

修复： 手动更新：

npm install -g jamdesk@latest

如果仍然失败，请检查 npm config get registry，并尝试 sudo npm install -g jamdesk@latest。