> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 修复文档站点上返回 404 的静态文件

> 诊断你添加到文档仓库中的文件（例如 JSON、PDF 或图片）为什么无法在 Mintlify 站点上通过预期 URL 加载。

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

## 确认 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 只会提供 [支持的文件类型](/docs/zh/create/files#supported-file-types) 中列出的类型。某些类型，例如 `.pdf`、`.txt`、`.xml`、`.csv` 和 `.zip`，只在企业版计划中提供。扩展名不受支持的文件即使存在于仓库中，也会返回 `404`。

## 检查文件大小

文件必须小于 20 MB。更大的文件不会被提供，需要托管到外部 CDN 或对象存储上。

## 排除认证的影响

启用了 [认证](/docs/zh/deploy/authentication-setup) 的文档站点不支持静态文件服务。即使文件存在且用户已登录，认证站点上的文件直链也会返回 `404`。如果站点需要认证，请把文件托管到外部服务上。

## 排除 `.mintignore` 及其他排除规则

检查文件是否匹配 `.mintignore` 中的某个模式。Mintlify 不会发布匹配 `.mintignore` 模式的文件，因此这些文件的 URL 不可用。参见 [排除文件发布](/docs/zh/organize/mintignore)。

Mintlify 还会自动忽略 `node_modules`、`build`、`dist` 和 `.git` 等目录。这些目录下的文件不会被提供。把文件移动到不会被自动忽略的目录，例如 `assets/` 或 `data/`。完整的默认忽略列表见 [默认忽略的模式](/docs/zh/organize/mintignore#default-ignored-patterns)。

## 添加文件后重新部署

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


## Related topics

- [文件](/docs/zh/create/files.md)
- [收集来自用户和 AI 智能体的页面反馈](/docs/zh/optimize/feedback.md)
- [AI 助手](/docs/zh/assistant/index.md)