katelya
412ce4c2e7
- 在 wrangler.toml 中为生产和预览环境添加 USERNAME 变量 - USERNAME 用于站长用户身份验证和管理权限控制 - 修复因缺失 USERNAME 导致的管理后台无法访问问题 - 更新部署指南，添加详细的500错误故障排除方案 - 包含完整的环境变量检查清单和验证步骤
260 lines
5.7 KiB
Markdown
260 lines
5.7 KiB
Markdown
# Cloudflare Pages 部署指南
|
||
|
||
## 🚨 500 Internal Server Error 解决方案
|
||
|
||
### 问题：部署成功但运行时500错误
|
||
|
||
**原因分析：**
|
||
|
||
部署日志显示构建成功，但访问网站时出现500错误，通常是由于环境变量配置问题导致的运行时错误。
|
||
|
||
**主要原因：**
|
||
|
||
1. **USERNAME 环境变量缺失** - 这是最常见的原因
|
||
2. D1 数据库绑定问题
|
||
3. 其他关键环境变量未设置
|
||
|
||
### 🎯 解决步骤
|
||
|
||
#### 第一步：设置 USERNAME 环境变量
|
||
|
||
在 Cloudflare Pages 控制台中：
|
||
|
||
1. 进入您的项目设置
|
||
2. 点击 "Settings" → "Environment variables"
|
||
3. 添加新的环境变量：
|
||
- **Variable name**: `USERNAME`
|
||
- **Value**: `katelya` (您的站长用户名)
|
||
- **Environment**: Production 和 Preview 都要添加
|
||
4. 点击 "Save"
|
||
5. 重新部署项目
|
||
|
||
#### 第二步：验证其他环境变量
|
||
|
||
确保以下环境变量已正确设置：
|
||
|
||
```bash
|
||
# 必需变量
|
||
USERNAME=katelya
|
||
NEXT_PUBLIC_STORAGE_TYPE=d1
|
||
NEXT_PUBLIC_SITE_NAME=KatelyaTV
|
||
NODE_ENV=production
|
||
|
||
# 推荐设置
|
||
NEXTAUTH_URL=https://your-domain.pages.dev
|
||
IMAGE_PROXY_ENABLED=true
|
||
```
|
||
|
||
#### 第三步：检查 D1 数据库绑定
|
||
|
||
1. 确保在 Cloudflare Pages 中绑定了 D1 数据库
|
||
2. 绑定名称应为 `DB`
|
||
3. 数据库应已初始化（运行过初始化脚本）
|
||
|
||
## 部署问题修复
|
||
|
||
### 问题1：Edge Runtime 配置错误
|
||
|
||
**错误信息：**
|
||
|
||
```text
|
||
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依赖问题
|
||
|
||
**错误信息：**
|
||
|
||
```text
|
||
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中运行构建命令：
|
||
|
||
```bash
|
||
pnpm run pages:build
|
||
```
|
||
|
||
#### 选项3：云端构建
|
||
|
||
直接在Cloudflare Pages的CI/CD环境中构建，因为云环境通常是Linux系统。
|
||
|
||
## 正确的部署步骤
|
||
|
||
### 1. 本地验证构建
|
||
|
||
```bash
|
||
# 生成运行时配置
|
||
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文件都包含：
|
||
|
||
```typescript
|
||
export const runtime = 'edge';
|
||
```
|
||
|
||
### 构建失败
|
||
|
||
1. 检查所有依赖是否安装完整
|
||
2. 确认TypeScript编译无错误
|
||
3. 验证环境变量配置
|
||
|
||
### 性能优化
|
||
|
||
- 已启用默认代码分割
|
||
- PWA缓存策略已配置
|
||
- 静态资源优化已开启
|
||
|
||
## 部署状态验证
|
||
|
||
部署完成后，访问以下端点验证：
|
||
|
||
- `/api/server-config` - 服务器配置
|
||
- `/api/debug/env` - 环境变量 (开发时)
|
||
- 主页 `/` - 前端页面
|
||
|
||
## 🔧 完整故障排除指南
|
||
|
||
### 500错误诊断清单
|
||
|
||
#### 1. 环境变量检查
|
||
|
||
```bash
|
||
# 在 Cloudflare Pages 控制台检查这些变量
|
||
USERNAME=katelya # ❌ 最常缺失
|
||
NEXT_PUBLIC_STORAGE_TYPE=d1 # ✅ 通常已设置
|
||
NEXT_PUBLIC_SITE_NAME=KatelyaTV # ✅ 通常已设置
|
||
NODE_ENV=production # ✅ 通常已设置
|
||
```
|
||
|
||
#### 2. D1 数据库检查
|
||
|
||
- [ ] D1 数据库是否已创建
|
||
- [ ] 数据库是否正确绑定到 Pages 项目
|
||
- [ ] 绑定名称是否为 `DB`
|
||
- [ ] 数据库是否已初始化
|
||
|
||
#### 3. 常见错误模式
|
||
|
||
| 错误现象 | 原因 | 解决方案 |
|
||
|---------|------|----------|
|
||
| 500 + 管理页面无法访问 | USERNAME 未设置 | 添加 USERNAME 环境变量 |
|
||
| 500 + 数据库相关错误 | D1 绑定问题 | 检查数据库绑定配置 |
|
||
| 构建成功但运行失败 | 环境变量缺失 | 检查所有必需变量 |
|
||
|
||
### 验证部署成功
|
||
|
||
部署完成后访问以下端点验证：
|
||
|
||
```bash
|
||
# 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. **立即回滚**
|
||
|
||
```bash
|
||
# 在 Cloudflare Pages 控制台
|
||
Deployments → 选择之前的工作版本 → Rollback
|
||
```
|
||
|
||
2. **保留环境变量**
|
||
|
||
```bash
|
||
# 记录当前所有环境变量配置
|
||
# 在新部署前先备份设置
|
||
```
|
||
|
||
3. **分步部署**
|
||
|
||
```bash
|
||
# 1. 先部署代码（不修改环境变量）
|
||
# 2. 验证基本功能
|
||
# 3. 逐步添加/修改环境变量
|
||
```
|
||
|
||
## 后续维护
|
||
|
||
1. 定期更新依赖
|
||
2. 监控部署日志
|
||
3. 备份数据库配置
|
||
4. 关注Cloudflare Pages更新
|
||
5. 定期检查环境变量配置
|
||
6. 监控网站运行状态
|