mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
c8e979f6cf
* docs: add help center article for static file 404 troubleshooting * docs: translate static-file-not-served help center article to es, fr, zh --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
42 lines
2.9 KiB
Plaintext
42 lines
2.9 KiB
Plaintext
---
|
||
title: "修复文档站点上返回 404 的静态文件"
|
||
description: "诊断你添加到文档仓库中的文件（例如 JSON、PDF 或图片）为什么无法在 Mintlify 站点上通过预期 URL 加载。"
|
||
keywords: ["static file not served", "404 asset", "JSON not found", "mintignore", "static assets", "file serving"]
|
||
---
|
||
|
||
Mintlify 会按文件在仓库中的位置对应的路径提供静态文件。如果像 `data/prices.json` 这样的文件在你请求 `https://docs.example.com/data/prices.json` 时返回 `404`，请依次排查下面的原因。要了解静态文件服务的工作原理和支持的文件类型列表，参见 [文件](/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 只会提供 [支持的文件类型](/zh/create/files#supported-file-types) 中列出的类型。某些类型，例如 `.pdf`、`.txt`、`.xml`、`.csv` 和 `.zip`，只在企业版计划中提供。扩展名不受支持的文件即使存在于仓库中，也会返回 `404`。
|
||
|
||
## 检查文件大小
|
||
|
||
文件必须小于 20 MB。更大的文件不会被提供，需要托管到外部 CDN 或对象存储上。
|
||
|
||
## 排除认证的影响
|
||
|
||
启用了 [认证](/zh/deploy/authentication-setup) 的文档站点不支持静态文件服务。即使文件存在且用户已登录，认证站点上的文件直链也会返回 `404`。如果站点需要认证，请把文件托管到外部服务上。
|
||
|
||
## 排除 `.mintignore` 及其他排除规则
|
||
|
||
检查文件是否匹配 `.mintignore` 中的某个模式。Mintlify 不会发布匹配 `.mintignore` 模式的文件，因此这些文件的 URL 不可用。参见 [排除文件发布](/zh/organize/mintignore)。
|
||
|
||
Mintlify 还会自动忽略 `node_modules`、`build`、`dist` 和 `.git` 等目录。这些目录下的文件不会被提供。把文件移动到不会被自动忽略的目录，例如 `assets/` 或 `data/`。完整的默认忽略列表见 [默认忽略的模式](/zh/organize/mintignore#default-ignored-patterns)。
|
||
|
||
## 添加文件后重新部署
|
||
|
||
当你推送到部署分支时，Mintlify 会构建你的文档。新添加的文件只有在下一次构建成功后才可用。打开控制台的部署历史，确认添加该文件的提交已成功构建，然后再重新测试 URL。
|