# 静态导出 (/zh/api/static-export/overview)
静态导出处于私有 Beta 阶段，需要企业协议。请联系 [sales@mintlify.com](mailto:sales@mintlify.com) 申请访问权限。
使用静态导出 API 以编程方式将站点预渲染为一组自包含的静态文件，并将结果作为单个包下载。导出的包为纯 HTML、CSS 和 JavaScript，没有运行时依赖，因此你可以将其托管在任何静态文件存储或 CDN 上。
## 静态包中的页面 URL [#静态包中的页面-url]
静态导出使用与包中的文件相对应的 `.html` URL。例如，`/guides/getting-started` 会变为 `/guides/getting-started.html`。此行为自动生效，无需任何配置。
canonical 和 sitemap 中的 URL 仍保持无扩展名。CloudFront 会自动解析这些 URL，但其他静态托管服务可能需要配置重写规则。
## 静态导出的工作原理 [#静态导出的工作原理]
静态导出以异步作业的形式运行。你为某个项目启动作业，然后轮询其状态，直至可下载该包。
使用你的项目 ID 调用 [启动静态导出作业](/zh/api/static-export/start-job)。API 会将作业加入队列并返回 `jobId`。
每个部署同一时间只能有一个处于活动状态的作业。如果该部署已有作业处于 `queued` 或 `running` 状态，端点将返回 `409`。该端点的速率限制为每个组织每小时最多启动 10 个作业。
使用 `jobId` 轮询 [获取静态导出作业状态](/zh/api/static-export/get-job-status)，直到 `status` 为 `completed`。完成后的响应中会包含 `bundleUrl`（指向该包的有时限预签名 S3 链接）、`sizeBytes` 以及 `expiresAt` 时间戳。
请在 `expiresAt` 之前下载该包。过期后，可再次调用状态端点以获取新的 `bundleUrl`，底层的导出文件仍可复用，仅链接有时限。
## 按部署方式的功能支持 [#按部署方式的功能支持]
可用功能取决于你的部署托管方式。气隙（air-gapped）部署没有出站网络访问权限，因此任何依赖 Mintlify 云服务的功能均不可用。标记为 **Configurable** 的功能会根据你的环境配置有所不同。
| 功能 | Cloud | Client-hosted | Air-gapped |
| ------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 文档搜索 | | Configurable | |
| AI 助手 | | Configurable | |
| 网页分析 | | Configurable | |
| API playground（"Try it"） | | | Configurable |
| 静态导出包 | | | |
## 端点 [#端点]
* [启动静态导出作业](/zh/api/static-export/start-job)：为项目将一个静态导出作业加入队列。
* [获取静态导出作业状态](/zh/api/static-export/get-job-status)：轮询作业状态；作业完成后，获取该包的预签名下载链接。
## 身份认证 [#身份认证]
使用你的 admin API 密钥对请求进行身份认证。你可以在控制台的 [API keys 页面](https://app.mintlify.com/settings/organization/api-keys) 生成 admin API 密钥。Admin API 密钥以 `mint_` 前缀开头，属于服务端机密——切勿在客户端代码中暴露。
从同一页面复制你的项目 ID，并将其用作 `projectId` 路径参数。
## 将包部署到你的 Enterprise Helm chart [#将包部署到你的-enterprise-helm-chart]
自托管的 Mintlify 通过 [`mintlify/enterprise`](https://github.com/mintlify/enterprise) 仓库中的 Helm chart 部署。当静态导出作业完成后，将 chart 指向 `bundleUrl`，部署环境便会从你自己的基础设施提供服务。
将 `values.yaml` 中的静态导出字段设置为 [获取静态导出作业状态](/zh/api/static-export/get-job-status) 返回的 `bundleUrl`。chart 会在启动时获取该包并将其作为当前版本提供服务。
```yaml title="values.yaml"
staticExport:
enabled: true
# Presigned S3 link returned by the Get static export job status endpoint.
bundleUrl: "https://mintlify-static-export-outputs-prod.s3.amazonaws.com/6520f3a1c9b1a20012ab34cd/export.tar.gz"
# Optional: pin to a specific export version for reproducible rollouts.
version: "2024-06-01"
```
使用 `helm upgrade` 应用更新后的 values。部署环境会下载该包，将其切换为当前站点，并从你的集群中提供服务。
```bash
helm upgrade --install mintlify mintlify/enterprise \
--namespace mintlify \
--create-namespace \
-f values.yaml
```
由于预签名链接会过期，每当你发布新内容时，都需要重新获取作业状态并再次执行升级，或使用 GitHub Actions 自动化整个流程。
## 使用 GitHub Action 自动化 [#使用-github-action-自动化]
以下模板工作流按计划或按需运行完整的导出流程。它会启动作业、轮询直至导出完成，然后将新的 `bundleUrl` 应用到 Helm chart。
```yaml title=".github/workflows/static-export.yml"
name: Publish static export
on:
workflow_dispatch:
schedule:
- cron: "0 6 * * *" # Daily at 06:00 UTC
env:
PROJECT_ID: proj_your_project_id
jobs:
export:
runs-on: ubuntu-latest
steps:
- name: Start static export job
id: start
run: |
JOB_ID=$(curl -s -X POST \
https://api.mintlify.com/v1/static-export/${{ env.PROJECT_ID }}/jobs \
-H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}" | jq -r '.jobId')
echo "job_id=$JOB_ID" >> "$GITHUB_OUTPUT"
- name: Wait for the job to complete and capture the bundle URL
id: bundle
run: |
for i in $(seq 1 60); do
RESPONSE=$(curl -s \
https://api.mintlify.com/v1/static-export/${{ env.PROJECT_ID }}/jobs/${{ steps.start.outputs.job_id }} \
-H "Authorization: Bearer ${{ secrets.MINTLIFY_ADMIN_KEY }}")
STATUS=$(echo "$RESPONSE" | jq -r '.status')
echo "status=$STATUS"
if [ "$STATUS" = "completed" ]; then
BUNDLE_URL=$(echo "$RESPONSE" | jq -r '.bundleUrl')
echo "bundle_url=$BUNDLE_URL" >> "$GITHUB_OUTPUT"
exit 0
fi
[ "$STATUS" = "failed" ] && exit 1
sleep 10
done
echo "Timed out waiting for the export job to complete." >&2
exit 1
- name: Deploy to the Helm chart
run: |
helm upgrade --install mintlify mintlify/enterprise \
--namespace mintlify \
--set staticExport.enabled=true \
--set staticExport.bundleUrl="${{ steps.bundle.outputs.bundle_url }}"
```
将你的 admin API 密钥保存为 `MINTLIFY_ADMIN_KEY` 仓库机密，并将 `PROJECT_ID` 设置为你项目的 ID。在部署之前，请配置集群凭据，例如使用 `azure/setup-helm` 和你的 Kubernetes 配置文件（`kubeconfig`）。