# 修复文档站点上返回 404 的静态文件 (/zh/help-center/static-file-not-served)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 361 · updated: 2026-09-23 -->

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

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

## 检查文件大小 [#检查文件大小]

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

## 排除认证的影响 [#排除认证的影响]

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

## 排除 `.mintignore` 及其他排除规则 [#排除-mintignore-及其他排除规则]

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

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

## 添加文件后重新部署 [#添加文件后重新部署]

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