> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIwMzg0MTFkMi02NTQ3LTQ3N2QtYWQxMi0xMTc3YzI2NmNlOTciLCJleHAiOjE3NzgzMjgyMjUsImlhdCI6MTc3ODMyNzkyNX0.gOXUdYjrjYj7Al1XLhpVzf4xtnokpYHrit6-yVK_05A
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.
# 发布您的文档
> 通过自动化工作流将您的 Fern 文档发布到生产环境和预发布环境。轻松设置自定义域名并管理部署。
当您准备让文档公开访问时，请使用 Fern CLI 发布它们。选择以下方法之一：[仅发布到生产环境](#publish-to-production)，或[同时发布到预发布和生产环境](#publish-to-staging-and-production)。
使用 [Fern Dashboard](https://dashboard.buildwithfern.com) 来管理 CLI 访问权限、连接您的 GitHub 仓库，并监控分析数据和失效链接。
## 发布到生产环境
对于单一生产环境站点（无预发布环境），运行以下命令来发布您的文档：
```bash
fern generate --docs
```
```bash Example
fern generate --docs
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
[docs]: ✓ All checks passed
[docs]: Published docs to https://plantstore.docs.buildwithfern.com
┌─
│ ✓ https://plantstore.docs.buildwithfern.com
└─
```
使用 GitHub Action 工作流在推送到 `main` 分支时自动发布您的文档。
使用 `fern token` 生成一个用于在 CI/CD 环境中对 Fern CLI 进行身份验证的令牌。该令牌特定于您在 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中定义的组织，并且不会过期。
```bash
fern token
```
将令牌添加为名为 `FERN_TOKEN` 的[仓库密钥](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)。
创建一个发布文档工作流（[示例](https://github.com/fern-api/docs/blob/main/.github/workflows/publish-docs.yml)），并引用该密钥。
```yaml .github/workflows/publish-docs.yml maxLines=7 startLine=21 {21}
name: Publish Docs
on:
push:
branches:
- main
jobs:
run:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Publish Docs
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: fern generate --docs
```
## 发布到预发布和生产环境
要在发布到生产环境之前在预发布站点上预览更改，请在您的 `docs.yml` 文件中定义[多个实例](/learn/docs/configuration/site-level-settings#instances-configuration)。配置多个实例后，发布时必须使用 `--instance` 标志。
将预发布和生产环境的 URL 添加到您的 `docs.yml` 文件中。URL 中不要包含 `https://`。
```yaml docs.yml
instances:
- url: plantstore-prod.docs.buildwithfern.com
- url: plantstore-staging.docs.buildwithfern.com
```
使用 `--instance` 标志发布到特定环境：
```bash
# 发布到预发布环境
fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
# 发布到生产环境
fern generate --docs --instance plantstore-prod.docs.buildwithfern.com
```
发布后，两个实例都将出现在 [Fern Dashboard](https://dashboard.buildwithfern.com) 中。
使用 GitHub Action 工作流在每次推送时自动部署到预发布环境，同时保持生产环境部署为手动触发。
使用 `fern token` 生成一个用于在 CI/CD 环境中对 Fern CLI 进行身份验证的令牌。该令牌特定于您在 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中定义的组织，并且不会过期。
```bash
fern token
```
将令牌添加为名为 `FERN_TOKEN` 的[仓库密钥](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)。
此工作流在更改推送到 `main` 分支时自动发布到您的预发布实例：
```yaml .github/workflows/publish-staging.yml maxLines=7
name: Publish Staging Docs
on:
workflow_dispatch:
push:
branches:
- main
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Validate configuration
run: fern check
- name: Publish to Staging
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
```
此工作流允许您从 GitHub Actions UI 手动触发生产环境部署：
```yaml .github/workflows/publish-production.yml maxLines=7
name: Publish Production Docs
on:
workflow_dispatch:
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Validate configuration
run: fern check
- name: Publish to Production
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: fern generate --docs --instance plantstore-prod.docs.buildwithfern.com
```
要部署到生产环境，请转到您的 GitHub 仓库中的 **Actions** 选项卡，选择工作流，然后点击 **Run workflow**。
## 托管
当您发布文档时，Fern 会为您托管它们。您也可以[将文档发布到自定义域名](/docs/preview-publish/setting-up-your-domain)。
### 自托管您的文档
如果您需要离线访问文档或想在自己的服务器上托管文档，Fern [也提供该选项](/docs/self-hosted/overview)。自托管文档对某些功能的访问受限（包括 Ask Fern 和分析功能）。
## 取消发布您的文档
要取消发布文档站点，请导航到 [Fern Dashboard](https://dashboard.buildwithfern.com) 中您站点的 **Settings** 页面，然后点击 **Unpublish**。这会使域名不再公开访问，但不会删除站点——您可以随时重新发布。这对于创建草稿站点或临时隐藏站点使其不被公众查看很有用。
## 常见错误
### No token found. Please set the FERN\_TOKEN environment variable or run `fern login`.
`fern generate --docs` 需要经过身份验证的会话才能发布。在本地运行 [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login)，或在您的 shell 或 CI 环境中设置 `FERN_TOKEN`。使用 [`fern token`](/learn/cli-api-reference/cli-reference/commands#fern-token) 生成适合 CI 的令牌。
### OpenAPI spec validation failed with N errors. Fix the errors above before generating docs.
文档引用的一个或多个 [OpenAPI 规范](/learn/docs/api-references/overview)存在致命验证错误。此消息上方的 `: ` 行标识了确切的问题——请在您的规范中修复这些问题，然后重新运行 `fern generate --docs`。