部署指南

概述

NotionNext 支持多种部署方式，本指南将详细介绍各种部署选项和最佳实践。

部署前准备

0. 本地统一基线（推荐）

为提升跨平台兼容性（Vercel / Cloudflare Pages / Netlify / EdgeOne Pages 等），本项目建议统一使用以下最简流程：

# Node 20（版本以仓库根目录 `.nvmrc` 为准，便于与各平台预装列表对齐）
nvm use || nvm install

# Yarn
npm i -g yarn

# 安装依赖 / 本地开发 / 构建
yarn
yarn dev
yarn build

1. 环境变量配置

创建 .env.local 文件并配置必要的环境变量：

# 必需配置
NOTION_PAGE_ID=your-notion-page-id

# 推荐配置
NEXT_PUBLIC_TITLE=你的博客标题
NEXT_PUBLIC_DESCRIPTION=你的博客描述
NEXT_PUBLIC_AUTHOR=作者名称
NEXT_PUBLIC_LINK=https://yourdomain.com

# 可选配置
REDIS_URL=redis://localhost:6379
NEXT_PUBLIC_ANALYTICS_GOOGLE_ID=G-XXXXXXXXXX

2. 构建测试

在部署前确保项目能够正常构建：

yarn build
yarn start

3. 质量检查

运行完整的质量检查：

yarn quality

Vercel 部署（推荐）

Vercel 是 Next.js 的官方部署平台，提供最佳的性能和开发体验。

自动部署

连接 GitHub
- 访问 Vercel
- 使用 GitHub 账号登录
- 导入你的 NotionNext 仓库
配置环境变量
- 在 Vercel 项目设置中添加环境变量
- 至少需要配置 NOTION_PAGE_ID
部署
- Vercel 会自动检测 Next.js 项目
- 每次推送到主分支都会自动部署

手动部署

# 安装 Vercel CLI
npm i -g vercel

# 登录
vercel login

# 部署
vercel

# 生产部署
vercel --prod

Vercel 配置文件

创建 vercel.json 文件进行高级配置：

{
  "framework": "nextjs",
  "buildCommand": "yarn build",
  "outputDirectory": ".next",
  "installCommand": "yarn",
  "functions": {
    "pages/api/**/*.js": {
      "maxDuration": 30
    }
  },
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    }
  ],
  "redirects": [
    {
      "source": "/feed",
      "destination": "/rss.xml",
      "permanent": true
    }
  ]
}

Netlify 部署

自动部署

连接仓库
- 访问 Netlify
- 连接你的 GitHub 仓库
构建设置
- Build command: yarn build
- Publish directory: out
- 环境变量: EXPORT=true
环境变量配置
- 在 Netlify 设置中添加环境变量

手动部署

# 构建静态文件
yarn export

# 安装 Netlify CLI
npm install -g netlify-cli

# 登录
netlify login

# 部署
netlify deploy --dir=out

# 生产部署
netlify deploy --prod --dir=out

Netlify 配置文件

创建 netlify.toml 文件：

[build]
  command = "yarn export"
  publish = "out"

[build.environment]
  EXPORT = "true"
  NODE_VERSION = "18"

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[redirects]]
  from = "/feed"
  to = "/rss.xml"
  status = 301

腾讯云 EdgeOne Pages

EdgeOne 构建阶段会按仓库中的 .nvmrc 切换 Node 版本。若控制台报错类似 Failed to switch to Node.js x.y.z，通常是因为平台上 未提供该补丁版本（例如仅有 20.18.0，而旧版本 .nvmrc 写了 20.20.0）。

处理方式：

保持上游：拉取最新 NotionNext，确认 .nvmrc 已与 EdgeOne「项目设置 → Node.js 版本」下拉列表中可选版本一致（一般为当前文件中的 20.18.x）。
自建仓库：在 EdgeOne 控制台选择与 .nvmrc 完全一致的 Node 版本；仍失败时检查构建日志是否仍在读取旧的 .nvmrc（需推送后再构建）。
package.json 中 engines.node 为 >=20 <25，在 Node 20 系列内均可构建；关键是 构建环境实际安装的版本能解析 .nvmrc。

构建命令与静态导出等与其它平台相同，按需配置环境变量（至少 NOTION_PAGE_ID）。

Docker 部署

Dockerfile

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED 1

RUN yarn build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Automatically leverage output traces to reduce image size
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "server.js"]

Docker Compose

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NOTION_PAGE_ID=${NOTION_PAGE_ID}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  redis_data:

部署命令

# 构建镜像
docker build -t notionnext .

# 运行容器
docker run -p 3000:3000 -e NOTION_PAGE_ID=your-id notionnext

# 使用 Docker Compose
docker-compose up -d

静态导出部署

适用于 GitHub Pages、Cloudflare Pages 等静态托管服务。

构建静态文件

yarn export

GitHub Pages 部署

GitHub Actions 配置

创建 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout
      uses: actions/checkout@v3
      
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Build
      run: yarn export
      env:
        NOTION_PAGE_ID: ${{ secrets.NOTION_PAGE_ID }}
        
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./out

配置 Secrets
- 在 GitHub 仓库设置中添加 NOTION_PAGE_ID

性能优化

1. 缓存配置

# Redis 缓存
REDIS_URL=redis://localhost:6379

# 内存缓存
ENABLE_CACHE=true

2. CDN 配置

# 图片 CDN
NEXT_PUBLIC_IMAGE_CDN=https://cdn.example.com

# 静态资源 CDN
NEXT_PUBLIC_STATIC_CDN=https://static.example.com

3. 压缩优化

# 启用压缩
NEXT_PUBLIC_COMPRESS=true

# 图片优化
NEXT_PUBLIC_IMAGE_OPTIMIZE=true

监控和日志

1. 错误监控

# Sentry
NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn

# LogRocket
NEXT_PUBLIC_LOGROCKET_ID=your-logrocket-id

2. 性能监控

# Vercel Analytics
NEXT_PUBLIC_VERCEL_ANALYTICS=true

# Google Analytics
NEXT_PUBLIC_ANALYTICS_GOOGLE_ID=G-XXXXXXXXXX

故障排除

常见问题

构建失败

# 清理缓存
yarn clean
rm -rf node_modules package-lock.json
yarn
yarn build

环境变量问题
```
# 检查环境变量
yarn quality
```

内存不足

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" yarn build

调试模式

# 启用调试
DEBUG=* yarn build

# Next.js 调试
NEXT_DEBUG=true yarn dev

安全检查清单

备份和恢复

数据备份

# 备份数据（按你的脚本体系执行）
# 例如：node scripts/backup-notion.js

# 备份配置文件
tar -czf config-backup.tar.gz .env.local blog.config.js

恢复流程

恢复代码仓库
恢复环境变量配置
重新部署应用
验证功能正常

更新和维护

定期维护

# 检查依赖更新
yarn check-updates

# 更新依赖
yarn upgrade

# 安全审计
yarn audit

# 性能分析
yarn bundle-report

版本升级

备份当前版本
更新代码
测试新功能
部署到生产环境
监控运行状态

FilesExpand file tree

DEPLOYMENT.md

Latest commit

History

DEPLOYMENT.md

File metadata and controls

部署指南

概述

部署前准备

0. 本地统一基线（推荐）

1. 环境变量配置

2. 构建测试

3. 质量检查

Vercel 部署（推荐）

自动部署

手动部署

Vercel 配置文件

Netlify 部署

自动部署

手动部署

Netlify 配置文件

腾讯云 EdgeOne Pages

Docker 部署

Dockerfile

Docker Compose

部署命令

静态导出部署

构建静态文件

GitHub Pages 部署

性能优化

1. 缓存配置

2. CDN 配置

3. 压缩优化

监控和日志

1. 错误监控

2. 性能监控

故障排除

常见问题

调试模式

安全检查清单

备份和恢复

数据备份

恢复流程

更新和维护

定期维护

版本升级