部署指南

docsblog-app 支持多种部署平台，你可以根据需求选择最合适的方案：

通用准备

无论选择哪个平台，都需要先完成以下步骤：

环境变量

复制 .env.example 为 .env，配置核心变量：

NEXT_PUBLIC_SITE_URL=https://your-domain.com
NEXT_PUBLIC_BASE_URL=https://your-domain.com
ENABLE_ADMIN=false

提示：Admin 后台仅用于本地开发，生产环境建议设为 false。

本地构建验证

pnpm install
pnpm build

构建成功后再进行平台部署。

Cloudflare Workers

使用 OpenNext 适配层部署到 Cloudflare Workers，支持 ISR 增量静态再生和 KV 缓存。

1. 注册 Cloudflare 账号

1. 访问 dash.cloudflare.com/sign-up 注册（免费套餐即可）
2. 记下你的 Account ID（Dashboard 首页右侧可见）

2. 创建 API Token

1. 进入 API Tokens 管理页面
2. 点击 Create Token → 选择 Edit Cloudflare Workers 模板
3. 确认权限：Account - Workers Scripts - Edit、Account - Workers KV Storage - Edit
4. 创建并复制 Token（仅显示一次）

3. 创建 KV Namespace

npx wrangler kv namespace create NEXT_INC_CACHE_KV

记下输出的 id。

4. 配置 wrangler.jsonc

填入 KV ID 和生产域名：

{
  "kv_namespaces": [
    {
      "binding": "NEXT_INC_CACHE_KV",
      "id": "<你的 KV ID>"
    }
  ],
  "env": {
    "production": {
      "vars": {
        "NEXT_PUBLIC_SITE_URL": "https://your-domain.com",
        "NEXT_PUBLIC_BASE_URL": "https://your-domain.com",
        "ENABLE_ADMIN": "false"
      },
      "kv_namespaces": [
        {
          "binding": "NEXT_INC_CACHE_KV",
          "id": "<你的 KV ID>"
        }
      ]
    }
  }
}

5. 部署

# 一键构建 + 部署
pnpm run deploy:cf

构建流程：aggregate → next build → opennextjs-cloudflare build → wrangler deploy

6. 验证

curl -sI https://your-domain.com | grep x-nextjs-cache
# 期望：x-nextjs-cache: HIT（缓存命中）

7. 自定义域名

进入 Cloudflare Dashboard → Workers & Pages → 你的 Worker → Settings → Domains & Routes → Add Domain。

Worker Custom Domain 绕过 CDN 缓存层，缓存由 KV 机制处理。

8. GitHub Actions 自动部署

项目支持推送到 main 分支后自动部署。在 GitHub 仓库配置：

创建 Environment CLOUDFLARE-DocsBlog-Prod（与 deploy.yml 对应），推送到 main 即可自动构建部署。

更详细的配置说明参见 docs/deploy-cloudflare.md。

Vercel

Vercel 是 Next.js 的官方托管平台，零配置即可部署。

1. 导入项目

1. 登录 Vercel Dashboard
2. 点击 Add New → Project
3. 选择你的 Git 仓库
4. Framework Preset 选择 Next.js（通常会自动识别）
5. 点击 Deploy

2. 配置环境变量

在 Vercel Dashboard → Project → Settings → Environment Variables 中配置：

NEXT_PUBLIC_ 前缀变量在构建时注入，修改后需重新部署。

3. 自动部署

连接 Git 仓库后，每次推送到 main 会自动部署：

git push → Vercel 构建（next build）→ 部署 → 完成

4. 缓存

Vercel 原生支持 ISR，无需额外配置：

• 页面设置 revalidate 即可启用
• 静态页面自动缓存到 Vercel Edge Network

5. 自定义域名

Dashboard → Project → Settings → Domains → 添加域名，Vercel 自动签发 SSL 证书。

6. 验证

curl -sI https://your-domain.com/ | grep -i x-vercel-cache

注意事项

• 项目中的 wrangler.jsonc 和 open-next.config.ts 是 Cloudflare 专用文件，Vercel 自动忽略
• Vercel 免费版限制：100GB 带宽/月，6000 构建分钟/月

更详细的配置说明参见 docs/deploy-vercel.md。

Node.js 自托管

使用标准 Node.js 服务器运行，适用于 VPS、云服务器、内网部署等场景。

1. 前提条件

• Node.js 18+（推荐 20 LTS）
• pnpm 包管理器

2. 构建与启动

pnpm install
pnpm build
pnpm start:node

# 指定端口
PORT=8080 pnpm start:node

3. 进程管理（PM2）

npm install -g pm2
pm2 start pnpm --name docsblog -- start:node
pm2 startup && pm2 save

4. 反向代理

Nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3005;
        proxy_http_version 1.1;
        proxy_set_header Upgrade {'$http_upgrade'};
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host {'$host'};
        proxy_set_header X-Real-IP {'$remote_addr'};
        proxy_set_header X-Forwarded-For {'$proxy_add_x_forwarded_for'};
        proxy_set_header X-Forwarded-Proto {'$scheme'};
        proxy_cache_bypass {'$http_upgrade'};
    }
}

Caddy

your-domain.com {
    reverse_proxy 127.0.0.1:3005
}

Caddy 自动签发和续期 SSL 证书。

5. 缓存

Node.js 部署使用 Next.js 默认的文件系统缓存：

• ISR 页面缓存在 .next/cache/ 目录
• 无需配置 KV 或 Redis

注意事项

• wrangler.jsonc 和 open-next.config.ts 是 Cloudflare 专用文件，忽略即可
• HTTPS 通过反向代理配置，不要在 Next.js 层处理

更详细的配置说明参见 docs/deploy-node.md。

常见问题

平台对比