Livebook 桌面应用(Tauri)开发与构建指南:从 tauri.sh 到自包含桌面安装包
Livebook 桌面应用(Tauri)开发与构建指南:从 tauri.sh 到自包含桌面安装包
本篇指南聚焦 Livebook 仓库中 rel/app 目录所承载的桌面应用工程——一个基于 Tauri 2、内嵌 Elixir 发行版的跨平台桌面壳。你将掌握 tauri.sh 提供的三条核心命令(开发、构建、打包安装运行)的完整用法,理解其背后的构建流水线(Elixir release 装配、OTP/Elixir/Hex 自包含 vendor、Rust 侧打包与代码签名),以及桌面运行时的启动脚本、托盘菜单、.livemd 文件关联、livebook:// 深链与自动更新机制,从而具备独立开发、调试和打包 Livebook Desktop 的能力。
一、定位:rel/app 是什么
Livebook 本身是一个 Phoenix 网页应用(见 mix.exs 中的 Phoenix 依赖与 default_release: :livebook),而 rel/app 目录则是在此基础上叠加的桌面应用工程:它用 Tauri(Rust 端)充当窗口壳与系统集成层,把 Elixir 服务器进程包装成 macOS / Windows / Linux 上的原生应用。目录结构如下:
- rel/app/tauri.sh —— 统一的开发/构建/安装命令入口;
- rel/app/src-tauri/ —— Tauri 工程本体(Rust 源码、配置、图标、权限声明);
- rel/app/env.sh.eex 与 rel/app/env.bat.eex —— 桌面发行版启动时的环境变量模板;
- rel/app/standalone.exs —— 把 OTP、Elixir、Hex、Rebar3 复制进发行包的构建脚本;
- rel/app/vm.args.eex —— 桌面版 Erlang VM 启动参数;
- rel/app/src-tauri/tauri.conf.json —— Tauri 打包配置(图标、安装目标、文件关联、更新源)。
从 mix.exs 的 target_deps(:app) 可以看到,桌面构建会额外引入 elixirkit(ElixirKit)依赖,它是连接 Tauri 壳与 Elixir 进程的桥接库;同时 Mix.target() == :app 时还会执行一次版本一致性校验(见后文)。
二、三条核心命令:开发、构建、安装运行
rel/app/README.md 给出了桌面工程的完整操作入口,全部经由 rel/app/tauri.sh 执行:
# 以开发模式运行应用
rel/app/tauri.sh dev
# 以发布模式构建应用(不安装、不启动)
rel/app/tauri.sh build
# 构建、安装并以发布模式运行应用
rel/app/tauri.sh app
命令需在仓库根目录(或任意目录给出完整相对路径)执行。三者行为差异如下:
| 命令 | 触发流程 | 典型用途 |
|---|---|---|
dev |
直接调用 cargo tauri dev,不预先做 Mix release |
桌面壳 + Elixir 热重载的日常开发 |
build |
先 mix release app,再 cargo tauri build 产出安装包 |
生成正式安装包(dmg / exe / AppImage) |
app |
先 mix release app,再 cargo tauri build,随后自动安装并启动 |
一键产出并体验最终安装形态 |
tauri.sh 同时把额外参数原样透传给 cargo tauri(脚本中对 dev/build/app 分支之外的参数执行 cargo tauri "$@"),例如 rel/app/tauri.sh dev --features xxx、rel/app/tauri.sh build --bundles nsis 这类 Cargo/Tauri 原生参数均可直接追加使用。
三、逐段拆解 tauri.sh:一个命令如何驱动全链路
rel/app/tauri.sh 是整个桌面构建的调度中心,核心逻辑可划分为五个环节。
3.1 环境准备:MIX_TARGET=app 与平台探测
export MIX_TARGET="app"
root_dir="$(cd "$(dirname "$0")" && pwd)"
mix_project_dir="${root_dir}/../.."
app="Livebook"
case "$(uname -s)" in
MINGW*|MSYS*|CYGWIN*) os=windows ;;
Darwin*) os=darwin ;;
Linux*) os=linux ;;
esac
MIX_TARGET=app 是触发 mix.exs 中桌面专属配置的开关:target_deps(:app) 引入 elixirkit,releases 中的 app 发布使用 rel_templates_path: "rel/#{Mix.target()}"(即 rel/app 下的模板),并注册 standalone_erlang_elixir 与 ElixirKit.Release.codesign 两个自定义构建步骤。
在 Windows 的 MSYS/MinGW 终端下,脚本还会做一次特殊的构建产物重定向:只要不在 CI 环境中,就把 MIX_HOME、MIX_DEPS_PATH、MIX_BUILD_PATH、HEX_HOME、CARGO_TARGET_DIR 等全部指向 /tmp/Livebook/ 下的独立目录,避免在共享源码目录(例如宿主机与虚拟机共用目录)时产生文件冲突;CI 场景则保持标准位置,便于缓存。
3.2 Profile 判定与 MIX_ENV
profile="release"
for arg in "$@"; do
if [ "$arg" = "--debug" ]; then profile="debug"; break; fi
done
if [ -z "${MIX_ENV:-}" ] && [ "$profile" = "release" ] && [ "$command" != "dev" ]; then
export MIX_ENV="prod"
fi
- 传入
--debug时 profile 为debug,否则为release; - 只要未显式设置
MIX_ENV,release 构建(build/app)会自动导出MIX_ENV=prod,确保编译优化与生产一致;dev命令不强制,保持开发环境变量; mix.exs中start_permanent: Mix.env() == :prod,即桌面发布包以永久启动模式运行。
3.3 先造 Elixir 发行包:mix_release
mix_release() {
(
cd "${mix_project_dir}"
mix setup
mix release app --overwrite --path "$release_root"
)
}
其中 release_root="$root_dir/src-tauri/rel-${os}"(例如 macOS 为 rel/app/src-tauri/rel-darwin)。mix setup 依次执行 deps.get、assets.setup(Bun 安装前端依赖并构建资源,见 mix.exs 的 aliases),随后以 --overwrite --path 方式把 app 发行包装配到 Rust 工程目录下,供后续 Tauri 打包把整个 rel-${os} 目录作为资源内嵌。
app release 的构建步骤定义在 mix.exs 的 releases 中:
app: [
applications: @release_apps, # livebook: :permanent, aws_credentials: :load
include_erts: false, # ERTS 由 standalone 步骤单独复制
rel_templates_path: "rel/#{Mix.target()}",
steps: [
:assemble,
&remove_cookie/1, # 移除 COOKIE,避免跨用户共享
&standalone_erlang_elixir/1, # 复制 OTP/Elixir/Hex/Rebar3 到 vendor
&ElixirKit.Release.codesign/1 # ElixirKit 代码签名步骤
],
entitlements: "#{__DIR__}/rel/app/src-tauri/App.entitlements"
]
与纯服务器版(livebook release 使用 rel/server 模板、include_erts: false 靠系统 ERTS)不同,桌面版必须自带完整工具链,因为桌面应用里的笔记本 runtime 需要独立启动 Erlang/Elixir 子节点。
3.4 自包含工具链:standalone.exs
rel/app/standalone.exs 中的 Standalone 模块负责把四样东西搬进发行包 vendor/livebook-<版本>/:
copy_otp:从当前编译环境的:code.root_dir()复制erts-<版本>/bin、erts-<版本>/include、整个lib与usr,并剥离文档与源码目录以减小体积;还会重写一个指向erlexec的erl包装脚本;copy_elixir:按versions文件锁定的版本,从builds.hex.pm下载对应 OTP 编译的 Elixir zip 解压到vendor/elixir,并保证elixir/elixirc/mix/iex(Windows 下为.bat版本)可执行;copy_hex:把本地 Hex 归档复制到vendor/archives;copy_rebar3:下载指定版本 rebar3 可执行文件放入vendor/rebar3。
当前仓库根目录 versions 锁定的版本组合为:elixir="1.20.1"、otp="28.1.1"、rebar3="3.24.0"。同时 mix.exs 顶部有硬性要求 System.otp_release() < "27" 即报错,构建机需使用 OTP 27+。发行包因此是离线自洽的:桌面用户无需预装 Elixir/Erlang 即可运行笔记本代码、使用 Mix.install/2。
3.5 Tauri 打包与安装运行
build/app 分支都会先执行 mix_release,再调用:
config="--config"
config_json="{\"bundle\":{\"resources\":{\"rel-${os}\":\"rel\"}}}"
cargo tauri build "$config" "$config_json" $bundles_flag "$@"
即通过 Tauri 的 --config 内联配置,把上一步生成的 rel-${os} 目录作为 bundle 资源打进安装包,运行时挂载为应用的 rel 资源目录(这正是 lib.rs 中 handle.path().resource_dir().unwrap().join("rel") 的取用路径)。
app 命令在 macOS 上额外加 --bundles app 只构建 .app,随后由 open_app 完成安装启动:
- macOS:通过
lsregister -u注销旧注册后,用open -W前台打开target/<profile>/bundle/macos/Livebook.app; - Windows:以静默模式执行 NSIS 安装器
Livebook*setup.exe //S,再从%LOCALAPPDATA%\Livebook\Livebook.exe启动应用。
构建目标在 rel/app/src-tauri/tauri.conf.json 中声明为 ["app", "dmg", "nsis", "appimage"],分别对应 macOS .app/.dmg、Windows NSIS 安装器、Linux AppImage。
四、版本一致性约束
桌面构建是双语言工程,Elixir 侧与 Rust 侧必须版本一致。mix.exs 在 Mix.target() == :app 时执行:
{cargo_output, 0} = System.cmd("cargo", ["pkgid"], cd: "#{__DIR__}/rel/app/src-tauri")
[_, cargo_version] = Regex.run(~r/#.+@(.+)$/, String.trim(cargo_output))
if @version != cargo_version do
Mix.raise("Version mismatch: mix.exs: ... Cargo.toml: ...")
end
当前 mix.exs 的 @version "0.20.0-dev" 与 rel/app/src-tauri/Cargo.toml 的 version = "0.20.0-dev" 保持一致。若你修改任一版本号,构建会立即报错,防止发行包版本漂移。Rust 侧依赖以 Tauri 2 系为主,并直接以 git 依赖引入 elixirkit,同时通过 [patch.crates-io] 替换了 tao 上游分支(用于 macOS 激活策略的定制)。
五、桌面运行时:从启动脚本到托盘菜单
5.1 启动环境:env.sh.eex / env.bat.eex
桌面版启动时会应用 rel/app/env.sh.eex(Windows 对应 rel/app/env.bat.eex)设定的环境,要点包括:
- 开机脚本:启动前先 source
$HOME/.livebookdesktop.sh(macOS/Linux)或%USERPROFILE%\.livebookdesktop.bat(Windows),允许用户注入自定义环境变量(详见下文); - 运行模式:
RELEASE_MODE=interactive;未设置时RELEASE_DISTRIBUTION=none(默认不开启分布式节点,避免占用端口与暴露 cookie); - 默认端口:
LIVEBOOK_PORT缺省为32123; - 关停按钮:
LIVEBOOK_SHUTDOWN_ENABLED缺省true,桌面应用可一键退出服务器; - Cookie 策略:未显式设置
RELEASE_COOKIE时,Unix 用/dev/urandom生成 32 位随机串,Windows 用时间+随机数拼接——同时支持通过LIVEBOOK_NODE/LIVEBOOK_COOKIE覆盖RELEASE_NODE/RELEASE_COOKIE,为高级分布式连接预留入口; - 工具链路径:把
vendor/livebook-<版本>/otp的 ERTS/OTP bin 与elixir/bin加入PATH,并令MIX_ARCHIVES、MIX_REBAR3指向 vendor 内的 Hex 归档与 rebar3。
5.2 Erlang VM 参数:vm.args.eex
rel/app/vm.args.eex 是桌面版专属的 VM 参数,与服务器版明显不同:
+sbwt none +sbwtdcpu none +sbwtdio none +Q 65536 -epmd_module Elixir.Livebook.EPMD
+sbwt none 系列关闭 busy-wait 调度以减少资源占用(桌面场景对功耗敏感),+Q 65536 提高端口上限,-epmd_module Elixir.Livebook.EPMD 则把 EPMD 替换为 Livebook 自定义模块(对应 lib/livebook/epmd.ex 与 escript 中的同名配置),用于管理运行时节点注册。
5.3 启动引导文件:~/.livebookdesktop.sh
项目根 README.md 的 "Livebook Desktop" 一节与 lib.rs 的 boot_script_template/0 共同说明了启动引导机制:桌面版每次开机都会执行 ~/.livebookdesktop.sh(macOS/Linux)或 %USERPROFILE%\.livebookdesktop.bat(Windows),常见用途包括:
- 修改
PATH,例如加入 Homebrew 目录(export PATH=/opt/homebrew/bin:$PATH); - 配置 Erlang 分发协议,例如
export ERL_AFLAGS="-proto_dist inet6_tcp"让 Livebook 能连接 IPv6 远端机器。
引导文件首次通过托盘菜单 "Open .livebookdesktop.sh / .bat" 时自动生成模板(见 ensure_boot_script/1)。修改后必须重启 Livebook 才生效,且配置错误可能导致应用无法启动,需谨慎编辑。
5.4 日志位置
桌面版日志由 init_tracing 写入各平台的标准日志目录(见 lib.rs 的 log_path/0):
| 平台 | 日志文件路径 |
|---|---|
| macOS | ~/Library/Logs/Livebook.log |
| Windows | %LOCALAPPDATA%\Livebook\Logs\Livebook.log |
| Linux | ~/.local/share/Livebook/Logs/Livebook.log |
Elixir 进程的 stdout/stderr 会按行被转发到 tracing(stderr 记为 ERROR、stdout 记为 INFO),Elixir 异常退出时 Rust 端会弹出包含退出码与日志路径的对话框。
5.5 托盘菜单与单实例/深链
rel/app/src-tauri/src/lib.rs 中的 run/0 展示了完整的桌面集成逻辑:
- 系统托盘:托盘图标菜单提供 Open、New Notebook、Copy URL(复制当前会话地址到剪贴板)、View Logs(打开
/logs)、启动引导文件、Settings、Check for Updates…、Quit 等条目,macOS 下为各条目绑定cmd+o、cmd+n、cmd+c、cmd+l、cmd+,、cmd+q快捷键;应用就绪(收到 Elixir 侧ready:<url>广播)后才启用菜单与左键点击; - 单实例:通过
tauri_plugin_single_instance保证只运行一个实例,第二实例启动时把携带的 URL(如livebook://...或.livemd文件路径)转交给首个实例打开(publish_open会在未就绪时先缓存,就绪后批量冲刷); - 深链:注册
livebook://scheme(见 tauri.conf.json 的plugins.deep-link配置),macOS 通过RunEvent::Opened接收系统传入的 URL; - 状态广播:Tauri 与 Elixir 通过
PubSub::listen("tcp://127.0.0.1:0")建立的本地 TCP pub/sub 通道通信,Elixir 侧在 debug 下用elixirkit::mix("phx.server", ...)(MIX_TARGET=app环境)启动,release 下用elixirkit::release(&release_dir, "app")从内嵌的rel资源启动。
六、安装包细节:文件关联、权限与自动更新
6.1 .livemd 文件关联
rel/app/src-tauri/tauri.conf.json 声明了 fileAssociations:*.livemd 对应 MIME text/x-livebook、角色 Editor;macOS 侧 Info.plist 还导出 UTI dev.livebook.livemarkdown,并把应用标记为 LSUIElement(无 Dock 图标、纯托盘常驻型应用)。桌面版因此可作为系统默认的 LiveMarkdown 编辑器:双击 .livemd 或把文件拖到 Dock/命令行参数传入,都会转化为打开请求(lib.rs 的 normalize_open_url 支持裸 Windows 路径、裸 Unix 路径与 livebook:///file:// URL)。
Linux 的 AppImage 默认不会自动注册文件关联,lib.rs 的 register_file_associations 在启动时手工写入共享 MIME 数据库(mime/packages/livebook.xml + update-mime-database),并调用 xdg-mime default <bin>-handler.desktop text/x-livebook 完成注册。
6.2 权限声明
- macOS 沙盒外授权(App.entitlements):允许 JIT、未签名可执行内存、dyld 环境变量、关闭库校验(Erlang VM 运行所必需),并开放摄像头与音频输入权限(对应 Livebook 的相机/麦克风交互能力);
- Tauri 能力白名单(rel/app/src-tauri/capabilities/default.json):主窗口默认开放
core:default、opener:default、dialog:allow-message与clipboard-manager:allow-write-text,其余能力按需收口。
6.3 自动更新
tauri_plugin_updater 被接入启动流程:应用启动时后台检查更新(check_for_updates_on_boot),发现新版本弹窗询问是否下载安装,确认后 download_and_install 并 app.restart();托盘 "Check for Updates…" 可手动触发同样流程,无更新时提示当前版本。更新源与签名公钥配置在 tauri.conf.json 的 plugins.updater 中,createUpdaterArtifacts: true 确保构建时产出更新所需的最小差异包。
七、常见开发实践与注意事项
- 开发模式:在仓库根目录执行
mix setup完成依赖与前端资源构建后,./rel/app/tauri.sh dev即可同时拉起 Tauri 窗口与mix phx.server(debug 分支),配合 LiveView 热重载调试 Elixir 侧逻辑; - 纯发布构建:
./rel/app/tauri.sh build会完整走一遍mix setup → mix release app → cargo tauri build,产物位于rel/app/src-tauri/target/release/bundle/<平台>/;构建机需具备 Rust 工具链(cargo)、Elixir 1.18+(mix.exs 要求~> 1.18)与 OTP 27+,Linux 还需系统依赖(如 webkit2gtk 等 Tauri 2 常规依赖); - Windows 子系统的环境重定向:在 MSYS/MinGW 下且非 CI 时,构建产物自动落到
/tmp/Livebook/,如需在 CI 中保留标准路径请设置CI环境变量; - 调试发布问题:桌面版与 Elixir 进程的通信通过
ELIXIRKIT_PUBSUB环境变量传递;Elixir 异常退出时会弹出含退出码的对话框,结合上文日志路径定位即可; - 修改引导脚本:涉及
PATH、ERL_AFLAGS等运行时配置时,编辑~/.livebookdesktop.sh(或 Windows 对应.bat)后重启应用,无需重新构建安装包。
八、结语
rel/app 把 Livebook 的 "Phoenix 网页应用" 与 "Tauri 原生壳" 结合为一条完整的桌面产线:tauri.sh 的三条命令背后,是 MIX_TARGET=app 触发的自包含 release(含 OTP/Elixir/Hex/Rebar3 的离线 vendor 目录)、Rust 侧的 ElixirKit 桥接与系统集成(托盘、深链、文件关联、自动更新),以及覆盖 macOS/Windows/Linux 的安装包产出与安装启动。理解这条链路后,无论是日常 tauri.sh dev 迭代、tauri.sh build 出包,还是排查桌面版启动问题,你都能直接从 rel/app/tauri.sh、rel/app/standalone.exs、rel/app/src-tauri/src/lib.rs 等源码中定位到对应的机制与依据。