跳转到主要内容
Mintlify 会按文件在仓库中的位置对应的路径提供静态文件。如果像 data/prices.json 这样的文件在你请求 https://docs.example.com/data/prices.json 时返回 404,请依次排查下面的原因。要了解静态文件服务的工作原理和支持的文件类型列表,参见 文件。

确认 URL 与仓库路径匹配

URL 路径与文件在仓库中的位置一致。提交到仓库根目录的 prices.json 文件会在 https://docs.example.com/prices.json 提供。位于 data/prices.json 的文件会在 https://docs.example.com/data/prices.json 提供。 常见错误:
  • 大小写不匹配。Prices.json 和 prices.json 是不同的 URL。
  • 文件只存在于功能分支。只有提交到 Mintlify 构建的那个分支的文件才会被提供。
  • 扩展名拼写错误。Mintlify 使用文件在仓库中的确切文件名来提供文件。
在 Git 提供商的 Web 界面中直接打开文件,确认它已存在于已部署的分支上。

检查文件类型是否受支持

Mintlify 只会提供 支持的文件类型 中列出的类型。某些类型,例如 .pdf、.txt、.xml、.csv 和 .zip,只在企业版计划中提供。扩展名不受支持的文件即使存在于仓库中,也会返回 404。

检查文件大小

文件必须小于 20 MB。Mintlify 不会提供更大的文件,因此请将其托管到外部 CDN 或对象存储上。在 Enterprise 方案中,你还可以使用 Git LFS 存储大文件。

排除认证的影响

启用了 认证 的文档站点不支持静态文件服务。即使文件存在且用户已登录,认证站点上的文件直链也会返回 404。如果站点需要认证,请把文件托管到外部服务上。

排除 .mintignore 及其他排除规则

检查文件是否匹配 .mintignore 中的某个模式。Mintlify 不会发布匹配 .mintignore 模式的文件,因此这些文件的 URL 不可用。参见 排除文件发布。 Mintlify 还会自动忽略 node_modules、build、dist 和 .git 等目录。这些目录下的文件不会被提供。把文件移动到不会被自动忽略的目录,例如 assets/ 或 data/。完整的默认忽略列表见 默认忽略的模式。

添加文件后重新部署

当你推送到部署分支时,Mintlify 会构建你的文档。新添加的文件只有在下一次构建成功后才可用。打开控制台的部署历史,确认添加该文件的提交已成功构建,然后再重新测试 URL。