2.5 KiB
2.5 KiB
10 本地运行与发布
本文档定义新项目的本地开发、构建、发布与环境管理规范。目标：让任何新同学在最短步骤内跑起来、可调试、可测试、可发布。
10.1 环境与工具链（建议）
- Node.js：LTS
- 包管理：pnpm（或 npm/yarn 任选其一，但全项目统一）
- 语言：TypeScript
- 代码规范：ESLint + Prettier（统一格式）
- 测试：Vitest/Jest（单元），Playwright（端到端，可选）
10.2 运行模式
10.2.1 开发模式
- 本地开发服务器
- 支持热更新（UI 与内容配置）
- 支持注入调试指令：
- 跳时间
- 生成物品
- 强制触发事件
- 固定随机种子
10.2.2 生产模式
- 静态资源构建输出（CDN 可部署）
- API 指向正式后端
- Debug 功能默认关闭（需权限或环境开关）
10.3 配置管理
推荐三层配置：
default：默认配置（安全值）env：按环境覆盖（dev/staging/prod）runtime：运行时下发（如内容包更新列表）
必须遵循：
- 配置不写死在代码里，使用环境变量/配置文件
- 任何密钥不得进入仓库
10.4 内容包发布流程（建议）
内容包与代码版本解耦：
- 内容策划提交内容包（JSON + 校验通过）
- CI 跑 Schema 校验、引用检查、权重表检查
- 内容包发布到 CDN/对象存储
- 后端返回最新内容包清单与版本号
- 客户端启动时拉取并缓存（可按需更新）
10.5 发布策略
10.5.1 版本号约定
- 客户端版本：SemVer
- 内容包版本：SemVer
- 存档版本：整数递增
saveVersion
10.5.2 回滚策略
- 客户端回滚：CDN 指向上一个构建
- 内容包回滚：清单回滚到上一版本
- 存档兼容：
- 向前兼容：旧存档可迁移到新版本
- 向后兼容：新存档回滚到旧版本通常不可行，需提示
10.6 监控与日志（建议）
- 客户端错误上报：
- JS 异常
- 资源加载失败
- 存档校验失败
- 关键事件埋点：
- 新手完成率
- 出行次数/死亡原因
- 关键科技解锁天数
- 任务链完成率
10.7 旧版仓库运行注意（仅用于参考）
当前仓库是静态网页 + AJAX 动态加载脚本，且在 loader.js 有域名跳转逻辑，本地直接打开可能会跳转到线上域名。旧版本地跑需要静态服务器并绕过域名限制。
新项目不会延续这种加载方式，会采用现代构建输出与模块化加载。