88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# 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 内容包发布流程（建议）
|
||
|
||
内容包与代码版本解耦：
|
||
|
||
1. 内容策划提交内容包（JSON + 校验通过）
|
||
2. CI 跑 Schema 校验、引用检查、权重表检查
|
||
3. 内容包发布到 CDN/对象存储
|
||
4. 后端返回最新内容包清单与版本号
|
||
5. 客户端启动时拉取并缓存（可按需更新）
|
||
|
||
## 10.5 发布策略
|
||
|
||
### 10.5.1 版本号约定
|
||
|
||
- 客户端版本：SemVer
|
||
- 内容包版本：SemVer
|
||
- 存档版本：整数递增 `saveVersion`
|
||
|
||
### 10.5.2 回滚策略
|
||
|
||
- 客户端回滚：CDN 指向上一个构建
|
||
- 内容包回滚：清单回滚到上一版本
|
||
- 存档兼容：
|
||
- 向前兼容：旧存档可迁移到新版本
|
||
- 向后兼容：新存档回滚到旧版本通常不可行，需提示
|
||
|
||
## 10.6 监控与日志（建议）
|
||
|
||
- 客户端错误上报：
|
||
- JS 异常
|
||
- 资源加载失败
|
||
- 存档校验失败
|
||
- 关键事件埋点：
|
||
- 新手完成率
|
||
- 出行次数/死亡原因
|
||
- 关键科技解锁天数
|
||
- 任务链完成率
|
||
|
||
## 10.7 旧版仓库运行注意（仅用于参考）
|
||
|
||
当前仓库是静态网页 + AJAX 动态加载脚本，且在 [loader.js](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/loader.js#L15-L23) 有域名跳转逻辑，本地直接打开可能会跳转到线上域名。旧版本地跑需要静态服务器并绕过域名限制。
|
||
|
||
新项目不会延续这种加载方式，会采用现代构建输出与模块化加载。
|
||
|