Livebook 桌面应用(Tauri)开发与构建指南:从 tauri.sh 到自包含桌面安装包

原创2026-10-11 20:05:482,240 阅读
文章标签:开发工具数据科学

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 上的原生应用。目录结构如下:

从 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 确保构建时产出更新所需的最小差异包。

七、常见开发实践与注意事项

  1. 开发模式:在仓库根目录执行 mix setup 完成依赖与前端资源构建后,./rel/app/tauri.sh dev 即可同时拉起 Tauri 窗口与 mix phx.server(debug 分支),配合 LiveView 热重载调试 Elixir 侧逻辑;
  2. 纯发布构建:./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 常规依赖);
  3. Windows 子系统的环境重定向:在 MSYS/MinGW 下且非 CI 时,构建产物自动落到 /tmp/Livebook/,如需在 CI 中保留标准路径请设置 CI 环境变量;
  4. 调试发布问题:桌面版与 Elixir 进程的通信通过 ELIXIRKIT_PUBSUB 环境变量传递;Elixir 异常退出时会弹出含退出码的对话框,结合上文日志路径定位即可;
  5. 修改引导脚本:涉及 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 等源码中定位到对应的机制与依据。

登录后查看全文
livebook