makepad-deployment

用途

本技能用于 Makepad 应用的打包与部署，覆盖 Makepad 所支持的全部平台，帮助将 Rust 编写的 Makepad UI 应用构建为可分发的安装包或可运行产物。

主要能力

按平台划分的打包工具与产物：

平台	工具	产物
桌面端	cargo-packager	.deb、.nsis、.dmg
Android	cargo-makepad	.apk
iOS	cargo-makepad	.app、.ipa
Web	cargo-makepad	Wasm + HTML/JS
CI/CD	makepad-packaging-action	GitHub Release 资产

使用方式

安装工具

安装桌面端打包工具：

cargo install cargo-packager --locked

安装资源处理工具 robius-packaging-commands（v0.2.1）：

cargo install --version 0.2.1 --locked \
    --git https://github.com/project-robius/robius-packaging-commands.git \
    robius-packaging-commands

安装移动端打包工具 cargo-makepad：

cargo install --force --git https://github.com/makepad/makepad.git \
    --branch dev cargo-makepad

配置 Cargo.toml

在 Cargo.toml 中添加 [package.metadata.packager] 打包配置，包括产品名、标识符、作者、描述、图标、输出目录等；通过 before-packaging-command 与 before-each-package-command 调用 robius-packaging-commands 收集资源；并在 resources 数组中列出 Makepad 内置资源（makepad_widgets、中文字体与 emoji 字体等）以及应用自身资源。注意 long_description 每行不超过 80 个字符。

各平台构建

Linux（Debian/Ubuntu）：先安装依赖（libssl-dev、libsqlite3-dev、pkg-config、binfmt-support、libxcursor-dev、libx11-dev、libasound2-dev、libpulse-dev），然后执行：

cargo packager --release

产物为 ./dist/ 下的 .deb 文件。

Windows（NSIS 安装包）：

cargo packager --release --formats nsis

产物为 ./dist/ 下的 .exe 安装程序。

macOS：

cargo packager --release

产物为 ./dist/ 下的 .dmg 文件。

Android：先安装工具链（可使用 --full-ndk 获取完整 NDK 支持），然后构建：

cargo makepad android build -p your-app --release

产物位于 ./target/makepad-android-app/。可通过 cargo makepad android run -p your-app --release 在设备或模拟器上运行。

iOS 模拟器：

cargo makepad apple ios \
    --org=com.yourcompany \
    --app=YourApp \
    run-sim -p your-app --release

产物为 ./target/makepad-apple-app/aarch64-apple-ios-sim/release/ 下的 .app。

iOS 真机（需要描述文件）：先在 Xcode 中创建同名 org/app 的空应用以生成描述文件，然后执行：

cargo makepad apple ios \
    --org=com.yourcompany \
    --app=YourApp \
    --profile=$YOUR_PROFILE_PATH \
    --cert=$YOUR_CERT_FINGERPRINT \
    --device=iPhone \
    run-device -p your-app --release

生成用于分发的 IPA：进入 ./target/makepad-apple-app/aarch64-apple-ios/release，创建 Payload 目录，复制 .app 后压缩为 .ipa。

Wasm：先安装工具链，然后运行：

cargo makepad wasm run -p your-app --release

产物位于 ./target/makepad-wasm-app/release/your-app/，包含 index.html、.wasm、.js 与 resources/。本地可用 python3 -m http.server 8080 提供服务。

平台专属配置

支持 [package.metadata.packager.deb]（depends、desktop_template、section）、[package.metadata.packager.macos]（minimum_system_version、frameworks、info_plist_path、entitlements、signing_identity）、[package.metadata.packager.dmg]（背景图、窗口尺寸、应用与文件夹位置）、[package.metadata.packager.nsis]（appdata_paths）等配置项。

GitHub Actions 打包

使用 Project-Robius-China/makepad-packaging-action@v1，它封装了 cargo-packager（桌面端）与 cargo-makepad（移动端），并可将产物上传到 GitHub Releases。示例 workflow 使用 actions/checkout@v4 后接该 action，参数为 --target x86_64-unknown-linux-gnu --release。

注意事项：桌面端包必须在对应操作系统 runner（Linux/Windows/macOS）上运行；iOS 构建需要 macOS runner；Android 构建可在任意系统 runner 上运行。

适用场景

适用于需要将 Makepad 应用发布到桌面、移动或 Web 平台的开发者，尤其是希望统一使用 cargo 工具链完成多平台打包，或在 GitHub Actions 中自动化构建与发布产物的团队。

限制与注意事项

各平台构建受操作系统限制：桌面端需匹配的 runner，iOS 需 macOS，Android 无此限制。
iOS 真机部署需要 Xcode 生成的描述文件与证书指纹。
若应用因资源缺失而崩溃，需检查 Cargo.toml 中 resources 数组是否包含全部 Makepad 资源、确认 before-packaging-command 执行成功、并检查 ./dist/resources/ 目录内容。
Android 出现 SDK 问题时可用 cargo makepad android install-toolchain --full-ndk 重装工具链。

参考文件

references/platform-troubleshooting.md：平台专属部署问题
references/makepad-packaging-action.md：GitHub Actions 打包参考
community/dora-studio-package-workflow.md：Dora Studio CI 打包示例
外部参考：cargo-packager 文档、robius-packaging-commands、cargo-makepad、makepad-packaging-action