常见错误
Node 版本过低
现象：npm run dev 或 npm run build 报 Vite 不支持当前 Node。
原因：Vite 8 要求 Node 20.19+ 或 22.12+。
解决：升级 Node（推荐 22 LTS），重新 npm install。
打开网站是空白或端口不对
现象：访问 localhost:3000 无服务。
原因：开发服务器是 Vite，默认 5173，不是 CRA 的 3000。
解决：使用 npm run dev，打开 http://localhost:5173。
刷新子路径 404
现象：首页正常，刷新 /zh/Activity 出现托管方 404。
原因：静态服务器没有把未知路径回退到 index.html。
解决：本地用 npm run preview 验证构建；生产在 Cloudflare Pages 确认 SPA 回退，或按 生产部署 配置 Nginx try_files。
页面出现翻译 key 原文
现象：界面显示 nav.home 或 title 而不是中文/英文。
原因：JSON 缺 key、中英文件不同步，或新命名空间未写入 src/i18n/index.js。
解决：补齐 src/locales/zh 与 en 的同一路径；新 namespace 必须 import 并加入 resources。
图片不显示
现象：裂图或 404。
原因：文件不在 public/images/、路径大小写错误，或写成了相对路径/src/ import。
解决：确认磁盘路径与 /images/... 一致。Linux CI 区分大小写。
构建成功但线上还是旧站
现象：push 后内容不变。
原因：Pages 发布目录仍为 build；或构建失败被忽略；或改了未连接的分支。
解决：Dashboard 将发布目录改为 dist，查看构建日志，确认生产分支。
语言切换后 404
现象：中文页正常，切 EN 进入缓冲页。
原因：链接写死了 /zh/...，或路由只注册在错误 path 下。
解决：内部跳转一律 LocalizedLink；路由写在 /:locale 内部。
误以为需要登录或 .env
现象：找不到 API key / 登录页。
原因：官网是纯静态站。
解决：不需要配置环境变量。招新账号在 Portal，与官网仓库无关。