Files

T

katelya 412ce4c2e7 fix: 添加缺失的USERNAME环境变量以修复500错误

- 在 wrangler.toml 中为生产和预览环境添加 USERNAME 变量
- USERNAME 用于站长用户身份验证和管理权限控制
- 修复因缺失 USERNAME 导致的管理后台无法访问问题
- 更新部署指南，添加详细的500错误故障排除方案
- 包含完整的环境变量检查清单和验证步骤

2025-10-01 23:30:03 +08:00

5.7 KiB

Raw Blame History

Cloudflare Pages 部署指南

🚨 500 Internal Server Error 解决方案

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

原因分析：

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

主要原因：

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

🎯 解决步骤

第一步：设置 USERNAME 环境变量

在 Cloudflare Pages 控制台中：

进入您的项目设置
点击 "Settings" → "Environment variables"
添加新的环境变量：
- Variable name: USERNAME
- Value: katelya (您的站长用户名)
- Environment: Production 和 Preview 都要添加
点击 "Save"
重新部署项目

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

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

# 必需变量
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 数据库绑定

确保在 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=d1
NEXT_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                          # ❌ 最常缺失
NEXT_PUBLIC_STORAGE_TYPE=d1              # ✅ 通常已设置
NEXT_PUBLIC_SITE_NAME=KatelyaTV          # ✅ 通常已设置
NODE_ENV=production                       # ✅ 通常已设置

2. D1 数据库检查

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

3. 常见错误模式

错误现象	原因	解决方案
500 + 管理页面无法访问	USERNAME 未设置	添加 USERNAME 环境变量
500 + 数据库相关错误	D1 绑定问题	检查数据库绑定配置
构建成功但运行失败	环境变量缺失	检查所有必需变量

验证部署成功

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

# 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更新
定期检查环境变量配置
监控网站运行状态

5.7 KiB Raw Blame History Unescape Escape