预览部署

为每个拉取请求获取唯一的预览 URL，让审阅者可以在实时环境中查看文档更改，然后再合并到生产环境。

预览部署可让你在合并到生产环境之前先查看文档更改的实际效果。每次预览都会生成一个可共享的 URL，并会在你推送新更改时自动更新。

预览 URL 默认对所有人可见。将预览链接分享给任何需要审阅你更改的人。

创建预览部署

通过拉取请求 (PR；亦称“合并请求”/Merge Request) 自动创建预览部署，或从你的控制台手动创建。

仅针对目标为你的部署用分支的拉取请求 (PR) ，才会自动创建预览。

当你创建拉取请求时，Mintlify 机器人会自动在拉取请求中添加一个链接，供你查看预览部署。每次你向该分支推送新的提交时，预览都会更新。

对于从 fork 发起的拉取请求，不会生成自动预览。Mintlify 的 GitHub 应用安装在你的文档存储库上，只能访问已显式安装它的存储库，因此无法读取贡献者的 fork，也无法基于它构建预览。

若要预览来自 fork 的更改，具有主存储库写入权限的维护者可以将贡献者的分支推送到主存储库的一个分支（或将 fork 合并到集成分支）。之后，GitHub 应用即可为从该分支发起的拉取请求构建预览。

你可以为任意 branch 手动创建预览。

你也可以使用 Trigger preview deployment API 端点以编程方式创建预览部署。这对于将预览创建集成到 CI/CD 流水线或自定义工具中非常有用。

当需要刷新内容，或在部署失败后重试时，可重新部署预览。

预览小部件会显示在预览部署中，帮助你浏览和审阅更新后的页面。该小部件以悬浮按钮的形式显示在预览部署页面的右下角。

该小部件只会显示在预览部署中，不会显示在已上线站点或本地预览中。

默认情况下，任何持有 URL 的人都可以访问预览部署。你可以通过要求所有预览进行组织身份验证，或为单个预览设置密码保护来限制访问。

将预览访问权限限制为 Mintlify 组织中的已认证成员。

为特定预览设置密码保护，以便与外部审阅者共享，而无需将他们添加到你的 Mintlify 组织中。此选项在创建手动预览时可用，当你的部署已启用组织身份验证时不会显示。

只要预览部署对应的源 branch 仍存在于你的仓库中，预览就会持续在线，并在每次推送时接收更新。

自动预览：拉取请求的预览在 PR 处于打开状态期间，以及合并或关闭后 (只要源 branch 仍存在) 都会保持可用。删除该 branch 后，预览会在下一次控制台同步时被移除。
手动预览：手动预览会一直在线，直到你删除它为止。重新部署手动预览会根据指定 branch 上的最新提交刷新其内容。
删除预览：在你的控制台中，前往 Previews，打开该预览，然后点击 Delete 立即将其移除。

预览 URL 按 branch 唯一。如果你删除了某个预览，之后又为同一 branch 重新创建预览，Mintlify 可能会分配一个新的 URL。

Mintlify 会自动生成预览 URL。子域名和域名不可配置，自定义域名仅保留用于你的生产部署。

如果预览部署失败，可以尝试以下故障排查步骤。

查看构建日志：在你的控制台中进入 Previews，并点击失败的预览。部署日志会显示导致失败的错误。
检查配置：
- 在配置的内容根目录中缺少 docs.json。如果你的 docs.json 位于子目录中，请确认 docs.json is in a subdirectory 设置指向正确的路径。
- docs.json 语法无效（例如，空文件或多余的尾随逗号导致 JSON 解析失败）。
- docs.json 中的 schema 错误，例如 theme 无效、navigation 格式错误或未解析的 $ref 值。
- 在导航中引用的文件路径缺失或不正确。
- MDX 文件中的 frontmatter 无效。
- 图片链接失效或缺少图片文件。
在本地验证：在本地运行 mint dev 和 mint validate，在推送到存储库之前先发现配置和构建错误。
检查最近的更改：查看当前分支中最近的提交，以确认哪些更改导致构建失败。