部署

OpenManual 支持将文档构建为静态站点，可以部署到任何静态托管平台。

前置条件

OpenManual 要求 Node.js >= 24.0.0。在部署前请确认你的构建环境满足此要求。

构建站点

openmanual build

构建完成后，静态文件会输出到 outputDir 配置指定的目录（默认为 dist）。

预览构建产物

openmanual preview

默认预览地址为 http://localhost:8080。可以指定端口和目录：

openmanual preview -p 3000 -d ./out

静态导出

OpenManual 默认使用 SSG（静态站点生成） 模式，无需额外配置即可生成可部署的静态文件。

运行 openmanual build 后，构建产物会输出到 outputDir 指定的目录（默认为 dist）。你可以将此目录部署到任何支持静态文件的托管平台。

部署到 Vercel

方式一：Git 集成（推荐）

通过连接 GitHub 仓库实现自动部署，每次推送代码时 Vercel 会自动构建和部署。

将项目推送到 GitHub
登录 Vercel Dashboard，点击 Add New → Project
选择你的 GitHub 仓库并导入
在 Configure Project 页面进行以下配置：
- Framework Preset: 选择 Next.js（或保持 Other）
- Build Command: npx openmanual build
- Output Directory: 与 openmanual.json 中的 outputDir 一致（默认为 dist）
- Install Command: npm install
在 Environment Variables 中添加：
- NODE_VERSION = 24（确保使用正确的 Node.js 版本）
点击 Deploy 开始部署

你也可以在项目根目录创建 vercel.json 来固化配置：

{
  "buildCommand": "npx openmanual build",
  "outputDirectory": "dist",
  "installCommand": "npm install"
}

注意: 如果你的 outputDir 不是默认的 dist，需要同步修改 vercel.json 中的 outputDirectory。

方式二：Vercel CLI

适合临时部署或测试场景：

# 安装 Vercel CLI
npm i -g vercel

# 在项目根目录执行部署
vercel

首次部署时按提示选择项目设置。后续更新只需再次执行 vercel 即可。

生产环境部署：

vercel --prod

部署到 Netlify

方式一：Git 集成（推荐）

将项目推送到 GitHub
登录 Netlify，点击 Add new site → Import an existing project
选择你的 GitHub 仓库
配置构建设置：
- Build command: npx openmanual build
- Publish directory: 与 openmanual.json 中的 outputDir 一致（默认为 dist）
在 Environment variables 中设置：
- NODE_VERSION = 24
点击 Deploy site

方式二：netlify.toml 配置

在项目根目录创建 netlify.toml：

[build]
  command = "npx openmanual build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "24"

将此文件提交到仓库后，Netlify 会自动读取配置。

部署到 GitHub Pages

方式一：GitHub Actions（推荐）

在仓库中创建 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Install openmanual
        run: npm install -g openmanual

      - name: Build
        run: openmanual build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

如果是自定义域名，则需要在托管平台配置对应的 DNS 解析和域名设置。

方式二：手动部署

# 构建站点
openmanual build

# 进入输出目录
cd dist

# 创建 gh-pages 分支并推送
git init
git checkout -b gh-pages
git add .
git commit -m "deploy"
git remote add origin <your-repo-url>
git push -f origin gh-pages

然后在仓库的 Settings → Pages 中选择 gh-pages 分支作为发布源。

常见问题

Node.js 版本不匹配

OpenManual 要求 Node.js >= 24.0.0。如果构建失败并出现语法错误或找不到模块，请检查 Node.js 版本：

node -v

各平台的版本设置方式：

平台	设置方式
Vercel	环境变量 `NODE_VERSION=24` 或 `package.json` 的 `engines.node`
Netlify	`netlify.toml` 的 `[build.environment]` 或环境变量
GitHub Actions	`actions/setup-node` 的 `node-version: 24`

自定义域名

使用自定义域名时，需要：

在 DNS 服务商处添加 CNAME 记录指向托管平台
在托管平台配置域名（Vercel/Netlify 在项目设置中添加，GitHub Pages 在仓库设置中添加）

部署

On this page