--- title: Archbee CLI 故障排除 slug: docs/cn/e1pg-archbee-cli createdAt: 2026-08-25T09:37:14.629Z --- ## 排查 Archbee CLI 问题 本指南涵盖了用户在使用 Archbee CLI 时遇到的最常见问题。 在提交支持工单之前，请先使用这些故障排查步骤。大多数问题都可以通过验证您的设置、检查身份验证或查看 CLI 命令选项来解决。 :::::ExpandableHeading{isOpen="true"} ### CLI 无法启动 **问题** 运行 `archbee` 失败或没有任何反应。 **推荐步骤** ::::WorkflowBlock :::WorkflowBlockItem 运行 `archbee 版本` 以验证 CLI 是否已安装。 ::: :::WorkflowBlockItem 如果命令不存在，请使用 npm 全局重新安装 CLI。 ::: :::WorkflowBlockItem 重新启动您的终端会话，然后再次尝试该命令。 ::: :::: **安装命令** ```bash npm install -g @archbee/cli ``` ::::: :::::ExpandableHeading ### 热重载无法正常工作 **问题** 更改未在本地预览中更新。 **推荐步骤** ::::WorkflowBlock :::WorkflowBlockItem 使用 `archbee Dev` 重新启动本地开发服务器。 ::: :::WorkflowBlockItem 验证您的项目包含受支持的配置文件。 ::: :::WorkflowBlockItem 检查您的文档文件夹是否未被忽略或排除。 ::: :::: ::::: :::ExpandableHeading ### 未检测到损坏的链接 运行： ```bash archbee broken-links ``` 请确保您的内部链接使用有效的相对路径。 ::: :::ExpandableHeading ### OpenAPI 同步问题 **问题** `sync-openapi` 在导入期间失败。 **常见原因** - 无效的 OpenAPI schema - 不受支持的引用 - 错误的文件路径 - 缺少身份验证 **推荐的第一步** 在同步之前验证 OpenAPI 文件。 ::: :::ExpandableHeading ### 身份验证错误 **401 未授权** 通常由以下原因导致： - 无效的 API key - 已过期的令牌 - 错误的 space ID **403 禁止访问** 通常是由于缺少权限或使用了只读团队 API key 导致。 ::: :::ExpandableHeading ### 发布问题 **问题** `发布空间` 失败。 **解决方案** 请验证： - 您具有写入权限 - space ID 正确 - API key 属于正确的组织 ::: :::::ExpandableHeading ### 推荐的调试工作流程 ::::WorkflowBlock :::WorkflowBlockItem 运行 `archbee 验证` 以验证项目结构。 ::: :::WorkflowBlockItem 运行 `archbee 损坏链接` 以扫描内部链接。 ::: :::WorkflowBlockItem 使用 `archbee --help` 查看命令用法和参数。 ::: :::: ::::: ## 其他资源 - 主要文档：[https://archbee.com/docs](https://archbee.com/docs) - npm 包：[https://www.npmjs.com/package/@archbee/cli](https://www.npmjs.com/package/@archbee/cli) - CLI 帮助：`archbee --help`