tianshu-engine/docs/guide/PUBLISHING.md

打包发布指南

准备工作

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

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

Web 版发布

一键打包

npm run pack:html

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

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

域名/CDN

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

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

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

桌面版发布

macOS

npm run pack:mac

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

Windows

npm run pack:win

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

桌面版命令行参数

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

# 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。