CLI 问题

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

**解决方法：**运行 jamdesk login 以启动新会话。这会替换 ~/.jamdeskrc 中的现有内容。

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

cat ~/.jamdeskrc

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

CLI 会在 9876 端口启动本地服务器，以接收浏览器的身份验证回调。如果始终未收到回调，登录会在 2 分钟后超时。

常见原因：

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

**解决方法：**复制终端中打印的 URL，然后手动打开。检查 URL 中的端口号是否与 CLI 正在监听的端口一致。

这在无头环境（SSH 会话、Docker 容器、CI runner）中很常见。即使没有可用的浏览器，登录 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，CLI 将没有可用的内容。

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

解决方法：

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

构建状态每 2 秒轮询一次。如果网络不稳定，CLI 最多容忍连续 3 次轮询失败，之后会放弃。

**解决方法：**按 Ctrl+C。构建会在后台继续运行。前往仪表板查看状态。退出时会打印链接。

上传成功，但构建本身失败了。你会在终端中看到构建服务返回的错误。

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

当文件看起来像机密文件时（.env、*.pem、*.key、credentials.json、以 secret 开头的文件），你会看到警告。这只是警告，不会阻止操作。

**解决方法：**将这些文件添加到 .gitignore，以便从上传内容中排除。如果这些文件是有意包含的（例如文档中的示例密钥文件），可以忽略该警告。

多种原因可能导致启动失败。

按以下顺序尝试：

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

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

解决方法：

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

# Pick a different port
jamdesk dev --port 3001

如需设置永久默认值，请将 "defaultPort": 3001 添加到 ~/.jamdeskrc 文件中。不要覆盖该文件，其中可能包含身份验证凭据。

如果开发服务器在编译过程中被终止（强制退出或系统崩溃），.next 缓存可能会损坏。下次启动时，你会看到“数据库损坏”或 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 扩展名，或使用了已重命名的旧路径。

CLI 会为接近匹配项提供更正建议（拼写错误在 3 个字符以内）。

**自动修复这些链接。**如果损坏的链接存在明确无歧义的正确目标（拼写错误的锚点或跨语言锚点漂移），请运行 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 中。

~/.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。