tongtongstudio
b9fd289caf
- 用 pnpm 替换 npm，锁定 pnpm@10.33.0，删除 package-lock.json 相关说明 - package.json 将渲染层依赖移入 devDependencies，减小 app.asar 体积 - 新增 electron:smoke 冒烟脚本与 icon 生成脚本 - win 平台设置 AppUserModelID，修复任务栏图标归组 - 清理 tsBuildInfoFile 输出路径至 node_modules/.tmp - 更新测试断言以匹配画幅遮罩、取景器缩放与模型库外部资产行为 - README 与打包指南补充 pnpm、镜像与常见问题说明
137 lines
4.9 KiB
Plaintext
137 lines
4.9 KiB
Plaintext
一力三期BMS - 故事AI导演工作台
|
||
================================
|
||
|
||
打包成exe的完整步骤：
|
||
|
||
（本文件是 README-PACKAGE.md 的纯文本简版，两者内容一致）
|
||
|
||
一、准备工作
|
||
|
||
1. 确保电脑已安装 Node.js 18 或更高
|
||
- 下载地址：https://nodejs.org
|
||
- 安装时勾选 "Add to PATH"
|
||
|
||
2. 安装 pnpm（本工程使用 pnpm，不再使用 npm / package-lock.json）
|
||
命令行执行：npm i -g pnpm
|
||
|
||
3. 打开命令行（CMD或PowerShell）
|
||
- 按 Win+R，输入 cmd，回车
|
||
- 或者在项目文件夹按住 Shift+右键，选择"在此处打开命令窗口"
|
||
|
||
二、打包步骤
|
||
|
||
第1步：进入项目目录
|
||
cd /d "本机上的项目目录" 例如：cd /d "D:\TongTongStudio\ai\jlmlh-3d-director"
|
||
|
||
第2步：安装依赖
|
||
pnpm install
|
||
|
||
第3步：构建前端
|
||
pnpm run build
|
||
|
||
第4步：打包exe
|
||
pnpm run electron:build:win
|
||
|
||
第5步：等待完成
|
||
- 首次打包需要下载Electron，约5-10分钟
|
||
- 打包完成后，exe文件在 release 目录
|
||
|
||
三、给用户使用
|
||
|
||
用户只需：
|
||
1. 双击 "故事AI导演工作台 Setup 1.0.0.exe"
|
||
2. 按提示安装（可自定义安装目录）
|
||
3. 桌面出现快捷方式
|
||
4. 双击打开即可使用
|
||
|
||
四、应用特性
|
||
|
||
✓ 无需安装任何运行时
|
||
✓ 桌面原生窗口体验
|
||
✓ 自动创建桌面快捷方式
|
||
✓ 支持自定义安装目录
|
||
✓ 支持开始菜单快捷方式
|
||
|
||
五、常见问题
|
||
|
||
Q: 打包失败怎么办？
|
||
A: 删除 node_modules 文件夹，重新执行 pnpm install，再打包。
|
||
注意：不要手动删除 node_modules 里的单个包（例如 node_modules\electron）。
|
||
绕过包管理器删包会让 pnpm 仍以为该依赖已安装，反而得到缺失或空壳的依赖目录。
|
||
|
||
Q: Electron 下载不下来？
|
||
A: 项目根目录 .npmrc 已配置 electron_mirror / electron_builder_binaries_mirror
|
||
指向 npmmirror。若仍失败，可先执行下面的命令再重试 pnpm install：
|
||
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
|
||
|
||
Q: exe文件太大？
|
||
A: Electron应用包含完整的浏览器引擎，这是正常的，约 77MB。
|
||
|
||
Q: 安装后打不开？
|
||
A: 右键以管理员身份运行，或检查杀毒软件是否拦截。
|
||
|
||
Q: 如何修改窗口大小？
|
||
A: 编辑 electron/main.cjs，修改 width 和 height 值。
|
||
|
||
Q: 如何修改应用图标？
|
||
A: 准备 256x256（建议 512x512）的 PNG 图标，命名为 icon.png，放到 public 目录，
|
||
重新打包。public/icon.png 已随仓库提供，也可以用零依赖脚本重新生成：
|
||
python scripts/generate_icon.py
|
||
|
||
六、开发调试
|
||
|
||
如需开发调试，运行：
|
||
pnpm run electron:dev
|
||
|
||
这会同时启动开发服务器和Electron窗口，支持热更新。
|
||
|
||
想验证"打包后的 dist 能否被 Electron 正常加载"：
|
||
pnpm run electron:smoke
|
||
|
||
冒烟脚本会确认：dist/index.html 能加载、React 成功挂载、渲染层无报错。
|
||
同时它也证明 dist 是自包含的（运行时不需要 node_modules）。
|
||
|
||
两种环境差异的处理：
|
||
1) 无 GPU 的机器（CI、远程桌面）需要额外参数：
|
||
pnpm exec electron --use-angle=swiftshader --use-gl=angle --no-sandbox scripts/test-electron.cjs
|
||
不加会报 WebGL 上下文创建失败，或页面加载 ERR_FAILED (-2)。
|
||
|
||
2) 若报 "Cannot read properties of undefined (reading 'whenReady')"，
|
||
说明终端里设置了 ELECTRON_RUN_AS_NODE（Electron 被退化成纯 Node），先清掉：
|
||
unset ELECTRON_RUN_AS_NODE (bash)
|
||
set ELECTRON_RUN_AS_NODE= (cmd)
|
||
|
||
七、技术说明
|
||
|
||
- 前端框架：React + TypeScript
|
||
- 3D引擎：Three.js + React Three Fiber
|
||
- 构建工具：Vite
|
||
- 桌面框架：Electron
|
||
- 打包工具：electron-builder
|
||
- 包管理器：pnpm
|
||
|
||
关于依赖分组：渲染层用到的库（three / react / zustand 等）都被 Vite
|
||
打包进 dist，主进程只用 Electron 自身模块，所以它们全部放在
|
||
devDependencies（构建期依赖）。electron-builder 会把 dependencies 里的包
|
||
整棵拷进 app.asar，留在 dependencies 会让安装包多出约 138MB 冗余体积。
|
||
新增依赖时请同样放进 devDependencies，除非它确实要在运行时被 require。
|
||
|
||
八、文件结构
|
||
|
||
storyai-3d-director-desk/
|
||
├── electron/ # Electron主进程
|
||
│ └── main.cjs # 主进程入口（CommonJS，无 preload）
|
||
├── scripts/ # 辅助脚本
|
||
│ ├── generate_icon.py # 生成 public/icon.png
|
||
│ └── test-electron.cjs # 加载 dist 的冒烟脚本
|
||
├── src/ # 前端源码
|
||
├── public/ # 静态资源（含 icon.png）
|
||
├── dist/ # 构建输出
|
||
├── release/ # 打包输出
|
||
├── docs/ # 设计文档
|
||
├── package.json # 项目配置
|
||
├── .npmrc # pnpm / 镜像配置
|
||
├── build-electron.bat # 一键打包脚本
|
||
├── 双击启动.bat # 浏览器方式启动（无需 Electron）
|
||
└── README-PACKAGE.md # 打包指南
|