构建与打包
基础命令
npm run package # 打包应用(含构建)→ out/Serpent-<platform>-<arch>/
npm run make # 生成安装包 → out/make/(macOS dmg / Windows zip;Linux 用 npm run make:appimage)
npm run verify:package # 校验打包产物(ASAR、native 模块、媒体组件)
package/make 的 prepackage/premake 钩子会先确保媒体依赖可用:
- 媒体二进制(
media-binaries ensure,必要时从锁定 release 恢复后校验来源与哈希) - ufbx WASM 产物(
verify-ufbx-wasm,哈希锁scripts/ufbx-wasm-lock.json) - 打包产物完整性(
verify:package:ASAR、better_sqlite3.node、Host utilities)
package/make 会更新 dev 的 Electron binary,跑完执行 npm run rebuild:native 恢复。
如果媒体可执行文件缺失,或本地文件与已晋升的 manifest 不一致,钩子会自动从
锁定的 Serpent-Build release 下载并重新校验。也可以手动执行同一流程:
npm run media:ensure
离线环境可设置 SERPENT_MEDIA_AUTO_ACQUIRE=0,此时校验失败会直接报错,不会联网下载。
发布流水线(release:local)
一键全流程:
npm run release:local
阶段:verify → media → package → e2e → make → checksums
| 阶段 | 内容 |
|---|---|
| verify | rebuild:native + verify:mainline(与 CI 相同门禁) |
| media | 从受控 URL 下载媒体包(media:acquire)+ 校验;linux-x64 与 linux-arm64 都与 macOS/Windows 走同一门禁(linux-arm64 在 bundle 晋升前为 build-required) |
| package | electron-forge package + verify:package |
| e2e | 对打包产物跑启动测试(test:e2e:packaged) |
| make | 生成安装包(Linux:优先 make:appimage:docker,并重命名为 Serpent-linux-x86-64-<ver>.AppImage 或 Serpent-linux-arm64-<ver>.AppImage) |
| checksums | 产物 SHA-256 manifest(带版本头) |
跳过慢阶段的选项:--skip-verify / --skip-media / --skip-e2e。单独跑某阶段:npm run release:<phase>(e2e 阶段为 npm run release:e2e:packaged)。
本地试跑(无媒体晋升时)
媒体包需先"晋升"(构建产物登记进 bundle-lock.json 的不可变 URL + 哈希)才能走正式流水线。本地已有匹配 source-lock.json 的产物时,跳过 provenance 校验:
SERPENT_MEDIA_SKIP_PROVENANCE=1 npm run release:local -- --skip-verify --skip-media
SKIP_PROVENANCE只用于本地试跑,正式发布必须走晋升流程。
另一条本地路径是 --build-media-locally:在本机用 vcpkg 完整构建媒体组件(scripts/media-build/*,耗时 1-3 小时)后自动以本地产物放行门禁:
npm run release:local -- --skip-verify --build-media-locally
版本
- 版本号在
package.json,semver 格式 - 提升:
npm version patch|minor|major(自动打 tag) - 每次流水线运行输出
Serpent v<版本>;checksum manifest 带版本头
平台
forge.config.ts 强制原生平台构建——pinned media 白名单为 darwin-arm64 / win32-x64 / linux-x64 / linux-arm64;Linux 也必须在本机(或同架构的 make:appimage:docker 容器内)打包,不支持交叉打包。各平台各自跑同一发布流水线。
Linux AppImage
npm run make:appimage # 本机 → out/make/appimage/Serpent-<ver>-x86_64.AppImage 或 Serpent-<ver>-aarch64.AppImage
npm run make:appimage:docker # Ubuntu 22.04 / glibc 2.35 基线,容器架构跟随宿主机(推荐发布构建)
npm run release:make # 优先 docker,并重命名为 Serpent-linux-x86-64-<ver>.AppImage 或 Serpent-linux-arm64-<ver>.AppImage
- linux-x64 与 linux-arm64 都内置与 macOS/Windows 相同的 pinned media bundle(
ffmpeg/ffprobe/oiiotool)。package的prePackage会执行media:ensure。bundle-lock.json里 linux-x64 目前为ready。linux-arm64 仍是build-required:media-v0.1.2没有serpent-media-linux-arm64.zip,在原生 aarch64 上跑scripts/media-build/linux-arm64.sh、上传 zip 并写回 URL 与 SHA-256 之前,media:acquire会失败,发不出现成 AppImage。本地试跑可用SERPENT_MEDIA_SKIP_PROVENANCE=1或--build-media-locally。 - Linux media bundle 必须在
ubuntu:22.04容器内用scripts/media-build/linux-*.sh构建(系统自带 GCC),保证ffmpeg/ffprobe/oiiotool最高只依赖 GLIBC 2.35,与 AppImage 的 22.04 基线一致;发布前用objdump -T <bin> | grep -o 'GLIBC_[0-9.]*' | sort -uV | tail -1核对。linux-x64 当前为media-v0.1.3(22.04 重建,源与配置同media-v0.1.2)。 - glibc 基线与 x86_64 相同(Ubuntu 22.04 / 2.35)。需要 FUSE(
libfuse2);无 FUSE 时--appimage-extract-and-run。X11 / Wayland 限制与 x86_64 相同。 - Release 上传名与应用内更新器一致:
Serpent-linux-x86-64-<ver>.AppImage或Serpent-linux-arm64-<ver>.AppImage(另附同名.sha256