# 打包发布指南

## 准备工作

```bash
npm install
npm run build          # 先构建，自动校验 JSON 合法性
```

构建产物在 `dist/`，是纯静态文件，可直接部署到任意 HTTP 服务器。

## Web 版发布

### 一键打包

```bash
npm run pack:html
```

生成 `release/mygame.zip`，上传到任意平台：

| 平台 | 上传方式 |
|------|---------|
| **itch.io** | 直接上传 zip |
| **Netlify** | 拖拽 `dist/` 文件夹到 Drop |
| **GitHub Pages** | 推送 `dist/` 到 `gh-pages` 分支 |
| **自有服务器** | 上传 `dist/` 到任意静态文件服务（Nginx, Apache, Caddy） |

### 域名/CDN

如果把素材放到 CDN，只需改一行：

```json
{
  "assetBase": "https://cdn.example.com/mygame/"
}
```

所有 `videoUrl: "scene_1/video.mp4"` 自动拼为 `https://cdn.example.com/mygame/scene_1/video.mp4`。

## 桌面版发布

### macOS

```bash
npm run pack:mac
```

生成 `release/MyGame-darwin-arm64/`。将整个文件夹打包为 `.dmg` 或直接分发文件夹。用户双击 `MyGame.app` 即可运行。

### Windows

```bash
npm run pack:win
```

生成 `release/MyGame-win32-x64/`。运行 `MyGame.exe`。

## 桌面版命令行参数

打包后的应用支持 `--scene` 参数指定剧情文件：

```bash
# macOS
./MyGame.app/Contents/MacOS/MyGame --scene=./scenes/my_story.json

# Windows
MyGame.exe --scene=./scenes/my_story.json
```

## 素材管理

### 本地开发

所有素材放在 `public/` 下，Vite 自动 serve。

### 生产发布

- 视频/音频通常较大（几百 MB），建议单独分发或放 CDN
- `.gitignore` 中已排除 `public/videos/`，视频不提交到 Git
- 打包脚本自动复制 `public/` 到 `dist/`，无需手动处理

### 目录规范

```
public/demo/           ← 示例数据
  scenes/demo.json
  locales/{zh,en,ja}.json
  intro/video.mp4
  shared/bgm.mp3

public/your_story/     ← 你的游戏（复制此结构）
  scenes/main.json
  locales/{zh,en}.json
  scene_1/video.mp4
```

## 常见问题

### Q: 构建时提示 "JSON 不合法"

检查 JSON 文件是否有多余逗号（最后一项不能有逗号）。

### Q: 打包后视频不加载

检查 `assetBase` 配置，确保路径拼接正确。开发模式 `assetBase: ""`，发布到 CDN 时改为完整 URL。

### Q: 打包体积太大

- 视频是最大的文件，建议单独制作低码率预览版（2Mbps）用于小体积分发
- 音频用 MP3 128kbps 即可
- 缩略图 JPG 质量 60% 足够

### Q: 如何制作安装包（.dmg / .exe 安装程序）

参考 `docs/electron/packaging-guide.md`。