# 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) 有域名跳转逻辑，本地直接打开可能会跳转到线上域名。旧版本地跑需要静态服务器并绕过域名限制。

新项目不会延续这种加载方式，会采用现代构建输出与模块化加载。