katelya
fb5be70529
- 在 wrangler.toml 中为生产和预览环境添加 PASSWORD 变量 - PASSWORD 是中间件验证的必需变量，缺失会导致500错误 - 更新部署指南，强调 PASSWORD 必须设置为 Plain text 类型 - 添加详细的环境变量类型设置说明和故障排除步骤 - PASSWORD 用于用户认证和签名验证，是系统核心安全机制
6.9 KiB
6.9 KiB
Cloudflare Pages 部署指南
🚨 500 Internal Server Error 解决方案
问题：部署成功但运行时500错误
原因分析：
部署日志显示构建成功，但访问网站时出现500错误，通常是由于环境变量配置问题导致的运行时错误。
主要原因：
- USERNAME 环境变量缺失 - 这是最常见的原因
- D1 数据库绑定问题
- 其他关键环境变量未设置
🎯 解决步骤
第一步：设置必需的环境变量
在 Cloudflare Pages 控制台中：
-
进入您的项目设置
-
点击 "Settings" → "Environment variables"
-
添加以下必需环境变量：
USERNAME 变量：
- Variable name:
USERNAME - Value:
katelya(您的站长用户名) - Type: Plain text
- Environment: Production 和 Preview 都要添加
PASSWORD 变量： ⭐ 关键变量
- Variable name:
PASSWORD - Value:
您设置的访问密码 - Type: Plain text (重要：不要选择密码类型)
- Environment: Production 和 Preview 都要添加
- Variable name:
-
点击 "Save"
-
重新部署项目
第二步：验证其他环境变量
确保以下环境变量已正确设置：
# ⭐ 关键必需变量（缺一不可）
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 数据库绑定
- 确保在 Cloudflare Pages 中绑定了 D1 数据库
- 绑定名称应为
DB - 数据库应已初始化（运行过初始化脚本）
部署问题修复
问题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 (推荐)
- 安装 Windows Subsystem for Linux (WSL)
- 在WSL环境中运行构建命令
选项2：使用 Git Bash
-
确保已安装 Git for Windows
-
在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=d1NEXT_PUBLIC_SITE_NAME=KatelyaTV- 其他变量见
wrangler.toml
3. 验证部署
部署成功后，检查：
- 所有API路由是否正常工作
- 静态页面是否正确生成
- Edge Runtime是否正常运行
常见问题排查
API路由问题
确保所有API文件都包含：
export const runtime = 'edge';
构建失败
- 检查所有依赖是否安装完整
- 确认TypeScript编译无错误
- 验证环境变量配置
性能优化
- 已启用默认代码分割
- 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）
紧急恢复方案
如果新部署出现问题：
-
立即回滚
# 在 Cloudflare Pages 控制台 Deployments → 选择之前的工作版本 → Rollback -
保留环境变量
# 记录当前所有环境变量配置 # 在新部署前先备份设置 -
分步部署
# 1. 先部署代码（不修改环境变量） # 2. 验证基本功能 # 3. 逐步添加/修改环境变量
后续维护
- 定期更新依赖
- 监控部署日志
- 备份数据库配置
- 关注Cloudflare Pages更新
- 定期检查环境变量配置
- 监控网站运行状态