Cloudflare Pages 部署指南

Cloudflare Pages 是一个现代化的静态网站和全栈应用托管平台。本指南将帮助你部署 Home Voice Box 项目。

概述

Cloudflare Pages 支持：

  • 自动从 Git 仓库部署
  • 预览部署（每个 Pull Request）
  • 无限带宽和请求
  • 全球 CDN 加速
  • Serverless Functions 支持

参考文档： Cloudflare Pages 官方文档

前置要求

  • Cloudflare 账户（免费账户即可）
  • GitHub、GitLab 或 Bitbucket 账户
  • 已准备好部署的项目代码

准备 Git 仓库

1. Fork 或克隆项目

# Fork 项目到你的 GitHub 账户
# 或克隆项目
git clone https://github.com/xinFengQi/ds-voice-box.git
cd ds-voice-box

2. 推送到你的仓库

# 添加你的远程仓库
git remote add origin https://github.com/your-username/ds-voice-box.git

# 推送代码
git push -u origin main

创建 Pages 项目

1. 登录 Cloudflare Dashboard

  1. 访问 Cloudflare Dashboard
  2. 登录你的账户

2. 创建 Pages 项目

  1. 在左侧菜单选择 Workers & Pages
  2. 点击 Create application
  3. 选择 Pages 标签
  4. 点击 Connect to Git
  5. 选择你的 Git 提供商（GitHub/GitLab/Bitbucket）
  6. 授权 Cloudflare 访问你的仓库
  7. 选择 ds-voice-box 仓库
  8. 点击 Begin setup

3. 配置项目设置

  • Project name：可以自定义（如：ds-voice-box）
  • Production branch：通常为 main 或 master
  • Framework preset：选择 None（本项目无需构建）
  • Build command：留空
  • Build output directory：留空或填写 /

点击 Save and Deploy 开始首次部署。

配置环境变量

部署完成后，需要配置环境变量。详细配置请参考 配置指南。

配置步骤

  1. 在项目页面，点击 Settings 标签
  2. 在左侧菜单选择 Variables and Secrets
  3. 在 Environment Variables 部分，点击 Add variable
  4. 添加以下环境变量：
    • ALIGENIE_NAME
    • ALIGENIE_CONTENT
    • HA_URL
    • HA_TOKEN
    • LOGIN_PATH
    • ADMIN_PASSWORD
    • KV_BINDING_NAME
  5. 为每个变量选择应用环境（Production、Preview 或 Both）
  6. 点击 Save

配置 KV Namespace

1. 创建 KV Namespace

  1. 在 Cloudflare Dashboard，选择 Workers & Pages
  2. 点击 KV 标签
  3. 点击 Create a namespace
  4. 输入名称（如：INTENTS_KV）
  5. 点击 Add

2. 绑定到 Pages 项目

  1. 回到你的 Pages 项目页面
  2. 进入 Settings → Functions
  3. 在 KV Namespace Bindings 部分，点击 Add binding
  4. 填写：
    • Variable name：与 KV_BINDING_NAME 环境变量的值一致（如：INTENTS_KV）
    • KV namespace：选择刚才创建的 namespace
  5. 点击 Save

3. 设置 KV_BINDING_NAME

在环境变量中设置 KV_BINDING_NAME， 值必须与步骤 2 中的 Variable name 完全一致。

配置自定义域名（可选）

  1. 在项目页面，进入 Custom domains
  2. 点击 Set up a custom domain
  3. 输入你的域名（如：voice.yourdomain.com）
  4. 按照提示配置 DNS 记录
  5. 等待 DNS 生效（通常几分钟）

配置完成后，你的项目可以通过自定义域名访问，同时也会保留默认的 *.pages.dev 域名。

部署流程

Cloudflare Pages 支持自动部署：

  • 自动部署：每次推送到主分支会自动触发部署
  • 预览部署：每个 Pull Request 会创建预览部署
  • 手动部署：可以在 Dashboard 中手动触发部署

查看部署状态

  1. 在项目页面，点击 Deployments 标签
  2. 可以看到所有部署历史和状态
  3. 点击部署可以查看详细日志

故障排除

部署失败

  • 检查构建日志中的错误信息
  • 确认项目结构正确（functions/ 目录存在）
  • 检查环境变量是否都已配置

Functions 不工作

  • 确认 functions/ 目录结构正确
  • 检查函数文件是否有语法错误
  • 查看 Functions 日志获取详细错误信息

KV 无法访问

  • 确认 KV Namespace 已正确绑定
  • 检查 KV_BINDING_NAME 环境变量是否正确
  • 确认绑定名称与环境变量值完全一致

参考资源