mintlify__docs/zh/api-playground/troubleshooting.mdx

---
title: "故障排查"
description: "排查 API 演练场配置中的常见问题，包括 OpenAPI 验证错误、缺失的端点和身份验证问题。"
keywords: ["API 故障排查", "OpenAPI 无效", "配置问题"]
boost: 3
---

如果你的 API 页面显示不正确，请先检查以下常见配置问题。

<AccordionGroup>
  <Accordion title="我的所有 OpenAPI 页面都是空白的">
    在这种情况下，很可能是 Mintlify 找不到你的 OpenAPI 文档，或者你的 OpenAPI 文档无效。

    在本地运行 `mint dev` 通常能暴露出其中一些问题。

    要验证你的 OpenAPI 文档是否通过校验：

    1. 访问[此校验器](https://editor.swagger.io/)。
    2. 切换到 **Validate text** 标签页。
    3. 粘贴你的 OpenAPI 文档。
    4. 点击 **Validate it!**

    如果下方出现的文本框带有绿色边框，说明你的文档已通过校验。
    这是 Mintlify 用于校验 OpenAPI 文档的同一套校验包，因此如果你的文档在这里通过校验，很大概率问题出在其他地方。

    此外，Mintlify 不支持 OpenAPI 2.0。如果你的文档使用该版本规范，可能会遇到此问题。你可以在 [editor.swagger.io](https://editor.swagger.io/) 上转换文档 (Edit &gt; Convert to OpenAPI 3) ：

    <Frame>
      ![展开 Edit 菜单并高亮“Convert to OpenAPI 3”菜单项的 Swagger Editor 截图。](/images/convert-oas-3.png)
    </Frame>
  </Accordion>

  <Accordion title="我的某个 OpenAPI 页面是完全空白的">
    这通常是由于页面 metadata 中的 `openapi` 字段拼写错误导致的。请确保
    HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径一致。

    <Note>
      Mintlify 会自动解析 `openapi` 引用与 OpenAPI 规范之间尾部斜杠的差异。
      例如，`GET /users/{id}/` 可以匹配规范中的路径 `/users/{id}`。
    </Note>

    下面是一个可能出错的示例：

    ```mdx get-user.mdx
    ---
    openapi: "GET /user/{id}"
    ---
    ```

    ```yaml openapi.yaml
    paths:
      "/users/{id}":
        get: ...
    ```

    请注意，`openapi` 字段中的路径是 `/user/{id}` (单数)，而 OpenAPI 文档中的路径是 `/users/{id}` (复数)。

    另一个常见问题是文件名拼写错误。如果你在 `openapi` 字段中指定了某个特定的 OpenAPI 文档，请确保文件名正确。例如，如果你有两个 OpenAPI 文档 `openapi/v1.json` 和 `openapi/v2.json`，你的 metadata 可能如下所示：

    ```mdx api-reference/v1/users/get-user.mdx
    ---
    openapi: "v1 GET /users/{id}"
    ---
    ```
  </Accordion>

  <Accordion title="我的构建报错 &quot;Failed to fetch OpenAPI file for anchor or tab&quot;">
    此错误表示 Mintlify 在构建期间无法从 `docs.json` 中 `openapi` 字段指向的 URL 下载 OpenAPI 文档。常见原因：

    - 主机不可达或仅在私有网络中可解析。
    - URL 需要身份验证（token、会话 cookie 或 IP 允许列表）。
    - 证书无效，或域名存在 DNS 问题。
    - 源站返回了瞬时 `5xx` 或超时。
    - 构建运行时，规范正在重新发布，URL 返回了部分或空响应。

    构建从公网下载 URL 且不带凭据，请在你的网络之外的机器上用 `curl` 确认能下载到该文档。要修复该错误，请改用以下方式之一：

    - **将规范提交到文档仓库。** 当源 URL 需要认证时，推荐使用此方式。将 `openapi` 字段指向仓库相对路径（例如 `"openapi": "openapi.json"`），并在修改 API 的同一次提交中更新该文件。
    - **通过稳定的公共 HTTPS URL 提供规范。** 将其托管在不需要认证的 CDN 或对象存储桶上，配备有效的 TLS 证书，并在每次请求都返回完整文档。

    有关完整的诊断流程（包括由 CI 在触发构建后才发布规范导致的间歇性失败），请参见[构建报错 "Failed to fetch OpenAPI file for anchor or tab"](/zh/help-center/openapi-url-fetch-fails-during-build)。
  </Accordion>
  <Accordion title="来自 API 操作台的请求无法正常工作">
    如果你配置了自定义 domain，这可能与反向代理有关。默认情况下，通过 API 操作台发起的请求会先向文档站点的 `/_mintlify/api/request` 路径发送一个 `POST` 请求。如果你将反向代理配置为只允许 `GET` 请求，那么这些请求都会失败。要解决此问题，请将反向代理配置为允许对 `/_mintlify/api/request` 路径的 `POST` 请求。

    或者，如果你的反向代理禁止接受 `POST` 请求，你可以在 `docs.json` 中通过 `api.playground.proxy` 设置，让 Mintlify 直接将请求发送到你的后端。详情请参见[设置文档](/zh/organize/settings-api)。使用此配置时，你必须在服务器上配置 CORS，因为请求是直接来自用户的浏览器，而不是通过你的代理。
  </Accordion>

  <Accordion title="OpenAPI 导航项未生成页面">
    如果你使用的是 OpenAPI 导航配置，但页面未生成，请检查以下常见问题：

    1. **缺少默认 OpenAPI 规范**：请确保在该导航元素上设置了 `openapi` 字段：

    ```json {5}
    "navigation": {
      "groups": [
        {
          "group": "API 参考",
          "openapi": "/path/to/openapi.json",
          "pages": [
            "GET /users",
            "POST /users"
          ]
        }
      ]
    }
    ```

    2. **OpenAPI 规范继承**：如果使用嵌套导航，确保子 groups 继承正确的 OpenAPI 规范，或为其分别指定自己的规范。

    3. **验证问题**：使用 `mint validate` 验证你的 OpenAPI 文档是否有效。
  </Accordion>

  <Accordion title="某些 OpenAPI 操作会出现在导航中，但其他则不会出现">
    1. **隐藏操作**：在你的 OpenAPI 规范中标记为 `x-hidden: true` 的操作不会出现在自动生成的导航中。
    2. **无效操作**：OpenAPI 规范中存在校验错误的操作可能会被跳过。请检查你的 OpenAPI 文档是否有语法错误。
    3. **手动与自动包含**：如果你从某个 OpenAPI 规范中引用了任意端点，只有被明确引用的操作会显示在导航中，其他页面不会自动添加。这也包括在子导航元素中被引用的操作。
  </Accordion>

  <Accordion title="Authorization 字段的描述过于通用或没有帮助">
    Mintlify 会根据安全方案类型自动为 API 操作台中的 `Authorization` 字段生成描述。你可以在 OpenAPI 规范的安全方案中添加 `description` 来覆盖它。

    ```json {7}
    {
      "components": {
        "securitySchemes": {
          "bearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "description": "在 [dashboard](https://example.com/dashboard) 中获取的 API key。发送时使用 `Bearer <key>` 的形式。"
          }
        }
      }
    }
    ```

    `description` 支持 Markdown，并会替换所有使用该安全方案的端点上自动生成的文本。
  </Accordion>

  <Accordion title="混合导航（OpenAPI 与 MDX 页面）工作异常">
    在导航中将 OpenAPI 操作与常规文档页面结合使用时：

    1. **文件冲突**：同一操作不能同时存在 `MDX` 文件和导航条目。比如，如果你有 `get-users.mdx`，就不要在导航中再包含 `"GET /users"`。如果你需要一个与该操作同名的文件，请为该端点使用 `x-mint` 扩展，让 href 指向其他位置。
    2. **路径解析**：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 `MDX` 文件位于预期的位置。
    3. **大小写敏感**：OpenAPI 操作匹配区分大小写。请确保在导航条目中 HTTP 方法使用大写。
  </Accordion>
</AccordionGroup>