Cloudflare Pages 部署与自定义域名配置指南

代码小郭2026年3月27日...大约 5 分钟

Cloudflare Pages 部署与自定义域名配置指南

本文档记录如何将 Next.js 静态站点同时部署到 GitHub Pages 和 Cloudflare Pages，并配置自定义域名。

项目配置

next.config.mjs

import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin('./i18n/config.ts');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 静态导出配置
  output: 'export',

  // 动态 basePath：GitHub Pages 需要，Cloudflare Pages 不需要
  // 设置环境变量 BASE_PATH=/your-repo-name 启用
  basePath: process.env.BASE_PATH || '',

  // 确保目录结构正确（/zh/ 而不是 /zh.html）
  trailingSlash: true,

  // 静态导出时图片优化需要禁用
  images: {
    unoptimized: true,
  },
};

export default withNextIntl(nextConfig);

package.json

确保使用 Next.js 15+ 版本：

{
  "dependencies": {
    "next": "^15.5.14",
    "next-intl": "^3.22.4"
  }
}

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: true

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build static site
        run: npm run build
        env:
          BASE_PATH: /your-repo-name

      - name: Add .nojekyll
        run: touch ./out/.nojekyll

      - name: Create index.html redirect
        run: |
          echo '<!DOCTYPE html>
          <html>
          <head>
            <meta charset="utf-8">
            <script>
              var lang = navigator.language || navigator.userLanguage;
              if (lang.startsWith("zh")) {
                window.location.href = "/your-repo-name/zh/";
              } else {
                window.location.href = "/your-repo-name/en/";
              }
            </script>
          </head>
          <body>
            <a href="/your-repo-name/en/">English</a> | <a href="/your-repo-name/zh/">中文</a>
          </body>
          </html>' > ./out/index.html

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './out'

  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

GitHub Pages 设置

进入 GitHub 仓库 → Settings → Pages
Source 选择 GitHub Actions
推送代码后自动触发部署

Cloudflare Pages 部署

方式一：Wrangler CLI 部署（推荐）

1. 安装并登录

# 登录 Cloudflare
npx wrangler login

浏览器会打开授权页面，确认授权即可。

2. 创建项目

# 创建 Pages 项目
npx wrangler pages project create your-project-name --production-branch main

3. 构建项目

# 本地构建（不需要设置 BASE_PATH）
npm run build

4. 创建根目录重定向页面

在 out/index.html 创建语言自动检测重定向：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Your Site</title>
  <script>
    var lang = navigator.language || navigator.userLanguage;
    if (lang.startsWith("zh")) {
      window.location.href = "/zh/";
    } else {
      window.location.href = "/en/";
    }
  </script>
</head>
<body>
  <p>Redirecting...</p>
  <p><a href="/en/">English</a> | <a href="/zh/">中文</a></p>
</body>
</html>

5. 部署

# 部署到 Cloudflare Pages
npx wrangler pages deploy ./out --project-name=your-project-name

方式二：Cloudflare Dashboard 部署

登录 Cloudflare Dashboard
点击 Workers & Pages → Create → Pages
选择 Connect to Git 或 Direct Upload
配置构建设置：
- Framework preset: Next.js (Static HTML Export)
- Build command: npm run build
- Build output directory: out

自定义域名配置

前提条件

域名已添加到 Cloudflare（如果不是，需要先添加）
域名的 DNS 已切换到 Cloudflare 的 Nameserver

检查域名 DNS 状态

# 查看域名的 NS 记录
nslookup -type=NS yourdomain.com

# 如果显示 xxx.ns.cloudflare.com，说明已在 Cloudflare
# 如果显示其他（如 hichina.com），需要先切换

将域名添加到 Cloudflare

登录 Cloudflare Dashboard
点击 Add a site
输入域名，选择 Free 计划

记下分配的 Nameserver，例如：

adam.ns.cloudflare.com
bella.ns.cloudflare.com

到域名注册商（如阿里云）修改 DNS 服务器为上述地址

配置 DNS 记录

进入 Cloudflare Dashboard → 选择域名 → DNS
添加以下记录：

类型	名称	内容	代理状态
CNAME	`@`	`your-project.pages.dev`	已代理（橙色云）
CNAME	`www`	`your-project.pages.dev`	已代理（橙色云）

在 Pages 项目中绑定域名

进入 Workers & Pages → 选择项目
Settings → Custom Domains
点击 Add Custom Domain
输入 yourdomain.com，确认
再次添加 www.yourdomain.com

验证

# 检查 DNS 是否生效
nslookup yourdomain.com

# 应该返回 Cloudflare 的 IP（104.x.x.x 或 172.x.x.x）

双平台兼容方案

问题

GitHub Pages 需要 basePath（如 /your-repo-name）
Cloudflare Pages 不需要 basePath
同一套代码需要同时支持两个平台

解决方案

创建动态路径工具函数 lib/utils.ts：

// 获取 basePath（GitHub Pages 需要，Cloudflare 不需要）
export function getBasePath(): string {
  // 服务端：检查环境变量
  if (typeof window === 'undefined') {
    return process.env.BASE_PATH || '';
  }

  // 客户端：只有 GitHub Pages 需要 basePath
  const hostname = window.location.hostname;
  // GitHub Pages: xxx.github.io
  if (hostname.includes('github.io')) {
    return '/your-repo-name';
  }
  // Cloudflare Pages 或其他: 不需要 basePath
  return '';
}

// 获取带 basePath 的资源路径
export function assetPath(path: string): string {
  // 确保路径以 / 开头
  const normalizedPath = path.startsWith('/') ? path : `/${path}`;

  // 服务端构建时使用环境变量
  if (typeof window === 'undefined') {
    const basePath = process.env.BASE_PATH || '';
    return `${basePath}${normalizedPath}`;
  }

  // 客户端运行时动态检测
  const hostname = window.location.hostname;
  if (hostname.includes('github.io')) {
    return `/your-repo-name${normalizedPath}`;
  }
  return normalizedPath;
}

使用方式

在组件中使用 assetPath() 包装所有静态资源路径：

import { assetPath } from '@/lib/utils';

// 图片
<img src={assetPath('/images/logo.png')} />

// 下载链接
<a href={assetPath('/downloads/file.exe')} download>

// 产品截图
const screenshots = [
  { url: assetPath('/images/screenshot1.png') },
  { url: assetPath('/images/screenshot2.png') },
];