从源码构建StemDeck桌面应用：Tauri v2+可移植Python运行时+FFmpeg SHA256校验的打包全解析-平芜编程栈

从源码构建StemDeck桌面应用：Tauri v2+可移植Python运行时+FFmpeg SHA256校验的打包全解析

【免费下载链接】stemdeckStemdeck is an modern stem extraction platform for musicians,producers and hobbyists, designed to isolate vocals, drums, bass, piano and guitar for practice, transcription, remixing, and creative audio workflows through a modern and interactive interface项目地址: https://gitcode.com/gh_mirrors/st/stemdeck

StemDeck 是一款面向音乐人、制作人和音频爱好者的现代音轨分离（stem extraction）平台，能把歌曲拆成人声、鼓、贝斯、钢琴等独立音轨。本文带你深入源码，完整解析它的桌面应用是如何打包的：Tauri v2 轻量桌面壳、可移植 Python 运行时，以及贯穿全程的 FFmpeg SHA256 完整性校验。

一、为什么打包难：一个应用，三种依赖

StemDeck 的架构是"Rust 桌面壳 + Python 后端"：

桌面壳：Tauri v2（Rust + 系统 WebView），位于 desktop/src-tauri/，负责窗口、拖拽、证书生成和后端进程管理；
Python 后端：FastAPI + Demucs 分离模型 + yt-dlp + FFmpeg，位于 app/；
前端 UI：纯 JS + Web Audio API，无构建步骤，位于 static/。

难点在于：用户机器上不能假设有 Python、FFmpeg、Node。所以每个打包脚本的核心任务都一样——把一整套可移植运行时塞进发布包里，并且用 SHA256 校验保证每个下载的二进制没被篡改。

二、Tauri v2 外壳：读懂两份核心配置

窗口与安全策略：tauri.conf.json

tauri.conf.json 定义了窗口尺寸（1280×820）、产品标识，以及一条很严格的 CSP：script-src 'self'加ipc:白名单，把 WebView 的攻击面压到最小。打包产物目标为appbundle（macOS 的.app）。

依赖清单：Cargo.toml 里的"打包密码学"

Cargo.toml 的注释非常诚实，几乎每条依赖都解释了"为什么需要它"：

sha2：对下载的运行时包做 SHA256 校验；
rcgen：在用户本机生成局域网访问的自签名证书（源码见 certs.rs）——随包附带证书等于把私钥发给每个下载者，所以干脆运行时现签；
tar/zip/zstd/flate2：解包 macOS 运行时归档（.tar.zst）和 Windows 更新包；
drag：把渲染好的音轨文件原生拖出到 DAW。

三、可移植 Python 运行时：PBS 而不是 venv

这是整个打包体系中最关键的一环。普通venv只有site-packages/，标准库仍指向原机器的路径——换台机器就废了。StemDeck 的解法是打包python-build-standalone（PBS）的完整安装：

用uv python install装一个自包含的 CPython（Linux 侧见 make-portable.sh 第 71 行附近）；
把sys.base_prefix整目录复制进包的python/，自带完整 stdlib；
删除EXTERNALLY-MANAGED标记，再用uv pip install --system把 app/ 装进去；
强制安装CPU-only 版 torch 2.6.0，并卸载孤儿 CUDA 运行时包（约 2.5 GB），把包体压进发布平台 2 GiB 的资产上限。

打包完成后还会做一次"瘦身体检"：删__pycache__、torch 的include/test、各包内置测试目录，但刻意保留.dist-info/RECORD——因为 NVIDIA 变体首次运行要往同一个 venv 里装 CUDA 版 torch，没有 RECORD 文件 pip 就没法卸载旧包。最后 collect_licenses.py 从 venv 里生成完整许可文件，MIT/BSD/Apache 都要求版权行随二进制分发。

四、FFmpeg 与外部二进制：SHA256 校验是硬门槛

桌面壳 main.rs 内置了一套"下载→校验→才可执行"的规则，按平台分三种策略：

平台	FFmpeg 来源	校验方式
Windows	BtbN 的 GitHub 构建（CDN 快）	拉取官方合并版`checksums.sha256`，按文件名匹配哈希
macOS	shaka-project 静态构建，evermeet 兜底	编译期钉死四个哈希（ffmpeg/ffprobe × arm64/x64），见 main.rs#L106-L116
Linux	johnvansickle 静态构建	钉死哈希 main.rs#L140-L141，因为上游只发布 MD5——"MD5 只证明没损坏，不证明没被劫持"

校验失败时行为是fail-closed：删掉文件并直接报错，绝不让一个没被验证过的二进制拿到执行权限。

同样的规则也用在 QuickJS 引擎上（约 2 MB，用来跑 yt-dlp 的 YouTube 签名求解脚本）：三个平台的打包脚本都固定版本v0.16.2+ 各自的 SHA256，不匹配就删除并中断构建。

五、三大平台打包脚本逐条走

macOS：runtime pack + .app + DMG

按 README.md 的命令顺序执行：

ARCH=arm64 scripts/macos/make-runtime-pack.sh # 构建 Python 运行时归档 ARCH=arm64 scripts/macos/make-app.sh # Tauri 构建 .app 并注入清单 ARCH=arm64 scripts/macos/make-dmg.sh # 打 DMG

make-runtime-pack.sh 的细节非常硬核：ditto保留符号链接复制 PBS Python、逐包import冒烟测试、清除 macOS 扩展属性防止 AppleDouble._*副文件混入 tar 包（曾导致 matplotlib 全部导入失败），最后把归档的SHA256 与大小写进 runtime-manifest.json——这个清单会被make-app.sh拷进StemDeck.app的 Resources，供首次启动时下载并校验运行时用。

Windows：一个 PowerShell 包出 CPU/GPU 两个变体

make-portable.ps1 产出StemDeck-Windows-x64/目录：

StemDeck.exe（Tauri 壳）+backend/（Python 后端代码）+python/（PBS 运行时）+portable.txt标记，解压即用；
-CpuOnly开关决定是否放置根目录cpu-only标记文件（GPU 检测只认包根目录的标记，避免污染用户数据目录）；
最后Get-FileHash -Algorithm SHA256生成<包名>.zip.sha256供用户核验；
-PublishUpdaterAssets额外产出精简的 app 层更新包（只有 exe + backend，不含 2 万文件的 Python 运行时）。

Linux：与 Windows 同构的 tar.gz

make-portable.sh 产出同样的布局（StemDeck二进制 +backend/+python/+cpu-only标记），打成.tar.gz并用sha256sum生成校验文件。FFmpeg 不随包分发（避免再分发问题），而是首次启动时由桌面壳下载并校验（见上一节）。

六、运行时指纹：app 更新的安全闸门

所有包里都藏着python/runtime-version.json，内容是runtimeId（形如py3.12-<uv.lock前16位哈希>）：

它由uv.lock 内容哈希 + 解释器版本推导，刻意不含包版本号（否则每次发版都会被判为不兼容）；
应用内更新器只替换StemDeck+backend/，永远不动python/（NVIDIA 变体会在首启改写它装 CUDA torch）；
只有新旧runtimeId一致时，更新器才提供"小体积 app 更新"，否则引导用户下载完整包。

这就是为什么打包脚本在"删缓存、剪 yt-dlp 提取器（prune_ytdlp_extractors.py）、裁剪测试目录"之后还要再跑一次全量 import 检查——裁剪如果误删了关键文件，必须在构建机上就炸掉，而不是在用户的机器上。

七、从零构建命令速查

目标	命令
macOS .app	`ARCH=arm64 scripts/macos/make-app.sh`
Linux 可移植包	`bash scripts/linux/make-portable.sh`（需 uv/cargo/node）
Windows 可移植包	`pwsh scripts/windows/make-portable.ps1 -CpuOnly`
本地开发跑后端	`./run.sh setup && ./run.sh start`，打开 http://localhost:8000

💡 源码获取：git clone https://gitcode.com/gh_mirrors/st/stemdeck，然后按需选择上表脚本即可。

总结

StemDeck 的打包方案值得借鉴的地方很清晰：Tauri v2 做薄壳（安全策略、证书、进程管理全在 Rust 侧几十行代码里说清楚）、PBS 完整 Python 保证可移植、SHA256 校验贯穿每个外部二进制（FFmpeg、QuickJS、运行时归档、更新包）、runtimeId 指纹让增量更新有安全边界。对想做"Rust + Python"混合桌面应用的同学，这三个脚本加 main.rs 就是一套可以直接参考的工程范本。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考