KatelyaTV/CLOUDFLARE_PAGES_DEPLOYMENT.md

Cloudflare Pages 部署指南

🚨 500 Internal Server Error 解决方案

问题：部署成功但运行时500错误

原因分析：

部署日志显示构建成功，但访问网站时出现500错误，通常是由于环境变量配置问题导致的运行时错误。

主要原因：

1. USERNAME 环境变量缺失 - 这是最常见的原因
2. D1 数据库绑定问题
3. 其他关键环境变量未设置

🎯 解决步骤

第一步：设置必需的环境变量

在 Cloudflare Pages 控制台中：

1. 进入您的项目设置

2. 点击 "Settings" → "Environment variables"

3. 添加以下必需环境变量：

   USERNAME 变量：

   • Variable name: USERNAME
   • Value: katelya (您的站长用户名)
   • Type: Plain text
   • Environment: Production 和 Preview 都要添加

   PASSWORD 变量： ⭐ 关键变量

   • Variable name: PASSWORD
   • Value: 您设置的访问密码
   • Type: Plain text (重要：不要选择密码类型)
   • Environment: Production 和 Preview 都要添加

4. 点击 "Save"

5. 重新部署项目

第二步：验证其他环境变量

确保以下环境变量已正确设置：

# ⭐ 关键必需变量（缺一不可）
USERNAME=katelya                          # 站长用户名
PASSWORD=your-secure-password             # 访问密码
NEXT_PUBLIC_STORAGE_TYPE=d1              # 存储类型
NEXT_PUBLIC_SITE_NAME=KatelyaTV          # 站点名称
NODE_ENV=production                      # 运行环境

# 推荐设置
NEXTAUTH_URL=https://your-domain.pages.dev
IMAGE_PROXY_ENABLED=true

⚠️ 重要提醒：

• PASSWORD 必须设置为 "Plain text" 类型，不要选择 "Secret" 或 "Password" 类型
• PASSWORD 的值应该与您之前在本地或其他环境中使用的密码一致

第三步：检查 D1 数据库绑定

1. 确保在 Cloudflare Pages 中绑定了 D1 数据库
2. 绑定名称应为 DB
3. 数据库应已初始化（运行过初始化脚本）

部署问题修复

问题1：Edge Runtime 配置错误

错误信息：

The following routes were not configured to run with the Edge Runtime:
  - /api/test/simple

Please make sure that all your non-static routes export the following edge runtime route segment config:
  export const runtime = 'edge';

解决方案：

✅ 已修复：删除了空的 /api/test/simple/route.ts 文件和相关目录。

验证：

所有API路由现在都正确配置了 export const runtime = 'edge';

问题2：Windows环境下的bash依赖问题

错误信息：

Error: spawn bash ENOENT

原因：

@cloudflare/next-on-pages 在Windows环境下需要bash来执行构建过程。

解决方案选项：

选项1：使用 WSL (推荐)

1. 安装 Windows Subsystem for Linux (WSL)
2. 在WSL环境中运行构建命令

选项2：使用 Git Bash

1. 确保已安装 Git for Windows

2. 在Git Bash中运行构建命令：

   pnpm run pages:build
   

选项3：云端构建

直接在Cloudflare Pages的CI/CD环境中构建，因为云环境通常是Linux系统。

正确的部署步骤

1. 本地验证构建

# 生成运行时配置
pnpm run gen:runtime

# 生成manifest
pnpm run gen:manifest

# Next.js 构建
npx next build

# Cloudflare Pages 适配 (在Linux/WSL环境中)
npx @cloudflare/next-on-pages

2. Cloudflare Pages 配置

在Cloudflare Pages控制台中设置：

构建配置：

• 构建命令: pnpm install --frozen-lockfile && pnpm run pages:build
• 构建输出目录: .vercel/output/static
• Node.js 版本: 20.x

环境变量： (已在 wrangler.toml 中配置)

• NEXT_PUBLIC_STORAGE_TYPE=d1
• NEXT_PUBLIC_SITE_NAME=KatelyaTV
• 其他变量见 wrangler.toml

3. 验证部署

部署成功后，检查：

1. 所有API路由是否正常工作
2. 静态页面是否正确生成
3. Edge Runtime是否正常运行

常见问题排查

API路由问题

确保所有API文件都包含：

export const runtime = 'edge';

构建失败

1. 检查所有依赖是否安装完整
2. 确认TypeScript编译无错误
3. 验证环境变量配置

性能优化

• 已启用默认代码分割
• PWA缓存策略已配置
• 静态资源优化已开启

部署状态验证

部署完成后，访问以下端点验证：

• /api/server-config - 服务器配置
• /api/debug/env - 环境变量 (开发时)
• 主页 / - 前端页面

🔧 完整故障排除指南

500错误诊断清单

1. 环境变量检查

# 在 Cloudflare Pages 控制台检查这些变量
USERNAME=katelya                          # ❌ 经常缺失
PASSWORD=your-password                    # ❌ 最关键，经常缺失或类型错误
NEXT_PUBLIC_STORAGE_TYPE=d1              # ✅ 通常已设置
NEXT_PUBLIC_SITE_NAME=KatelyaTV          # ✅ 通常已设置
NODE_ENV=production                       # ✅ 通常已设置

特别注意 PASSWORD 变量：

• ✅ 正确：类型选择 "Plain text"
• ❌ 错误：类型选择 "Secret" 或 "Password"
• ❌ 错误：值为空或包含特殊字符

2. D1 数据库检查

• D1 数据库是否已创建
• 数据库是否正确绑定到 Pages 项目
• 绑定名称是否为 DB
• 数据库是否已初始化

3. 常见错误模式

错误现象	原因	解决方案
500 错误	PASSWORD 未设置或类型错误	设置 PASSWORD 为 Plain text 类型
500 + 管理页面无法访问	USERNAME 未设置	添加 USERNAME 环境变量
重定向到 /warning 页面	PASSWORD 环境变量缺失	检查 PASSWORD 变量设置
500 + 数据库相关错误	D1 绑定问题	检查数据库绑定配置
构建成功但运行失败	关键环境变量缺失	检查 USERNAME 和 PASSWORD

验证部署成功

部署完成后访问以下端点验证：

# 1. 基本页面
https://your-domain.pages.dev/          # 主页
https://your-domain.pages.dev/login     # 登录页

# 2. API 端点
https://your-domain.pages.dev/api/server-config  # 服务器配置
https://your-domain.pages.dev/api/debug/env      # 环境变量（开发时）

# 3. 管理功能
https://your-domain.pages.dev/admin     # 管理后台（需要正确的 USERNAME）

紧急恢复方案

如果新部署出现问题：

1. 立即回滚

   # 在 Cloudflare Pages 控制台
   Deployments → 选择之前的工作版本 → Rollback
   

2. 保留环境变量

   # 记录当前所有环境变量配置
   # 在新部署前先备份设置
   

3. 分步部署

   # 1. 先部署代码（不修改环境变量）
   # 2. 验证基本功能
   # 3. 逐步添加/修改环境变量
   

后续维护

1. 定期更新依赖
2. 监控部署日志
3. 备份数据库配置
4. 关注Cloudflare Pages更新
5. 定期检查环境变量配置
6. 监控网站运行状态