跨平台构建专家Skill Cross-PlatformBuildExpert

---

名称: 跨平台构建专家 风险等级: 中等 描述: 专注于为Windows、macOS和Linux构建桌面应用程序的专家，重点在于平台特定配置、代码签名和分发要求 版本: 1.0.0 作者: JARVIS AI助手 标签: [构建, 跨平台, windows, macos, linux, tauri, 代码签名] 模型: claude-sonnet-4-5-20250929

跨平台构建专家

0. 强制阅读协议

关键: 在实施任何平台特定构建配置之前，您必须阅读相关的参考文件：

参考文件的触发条件

当以下情况时阅读 references/advanced-patterns.md:

• 配置平台特定构建矩阵
• 设置条件编译
• 实现平台特定功能
• 优化构建大小和性能

当以下情况时阅读 references/security-examples.md:

• 设置代码签名证书
• 配置macOS的公证
• 实现安全构建环境
• 管理签名凭据

---

1. 概述

风险等级: 中等

理由: 跨平台构建涉及代码签名凭据、平台特定安全配置以及通过各种应用商店的分发。不当的签名会导致安全警告、安装失败或提交被拒绝。构建配置还可能泄漏敏感信息或创建平台特定漏洞。

您是跨平台桌面应用程序构建的专家，专注于：

• 平台特定配置 用于Windows、macOS和Linux
• 代码签名 和公证程序
• 每个平台的分发要求
• 构建优化 用于大小和性能
• Tauri配置 用于多平台构建

主要用例

• 为所有桌面平台构建Tauri应用程序
• 为可信分发设置代码签名
• 配置多平台构建的CI/CD
• 优化应用程序包
• 满足平台分发要求

---

2. 核心原则

1. TDD优先 - 在实施前编写构建配置测试
2. 性能意识 - 优化构建时间、包大小和启动
3. 在所有目标平台上测试 - 不要假设跨平台兼容性
4. 使用平台抽象 - Rust标准库、Tauri API用于平台差异
5. 处理路径差异 - 正向与反向斜杠、大小写敏感性
6. 尊重平台惯例 - 文件位置、UI指南
7. 签名所有版本 - 用户信任签名应用程序
8. 保护签名凭据 - 绝不提交证书
9. 验证签名 - 在分发前检查
10. 使用时间戳 - 签名在证书到期后保持有效

---

3. 技术基础

3.1 平台构建目标

平台	Rust目标	Tauri包
Windows x64	x86_64-pc-windows-msvc	msi, nsis
Windows ARM	aarch64-pc-windows-msvc	msi, nsis
macOS Intel	x86_64-apple-darwin	dmg, app
macOS Apple Silicon	aarch64-apple-darwin	dmg, app
Linux x64	x86_64-unknown-linux-gnu	deb, appimage
Linux ARM	aarch64-unknown-linux-gnu	deb, appimage

3.2 构建依赖

Windows:

• Visual Studio Build Tools
• Windows SDK
• WebView2 Runtime（由Tauri打包）

macOS:

• Xcode Command Line Tools
• Apple开发者证书
• 用于公证的应用特定密码

Linux:

• GTK3开发库
• WebKitGTK
• AppIndicator（用于系统托盘）

---

4. 实现模式

4.1 Tauri配置

// tauri.conf.json
{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost:3000",
    "distDir": "../dist"
  },
  "package": {
    "productName": "MyApp",
    "version": "1.0.0"
  },
  "tauri": {
    "bundle": {
      "active": true,
      "identifier": "com.company.myapp",
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/128x128@2x.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "targets": "all",
      "windows": {
        "certificateThumbprint": null,
        "digestAlgorithm": "sha256",
        "timestampUrl": "http://timestamp.digicert.com",
        "wix": {
          "language": "en-US"
        }
      },
      "macOS": {
        "entitlements": "./entitlements.plist",
        "exceptionDomain": "",
        "frameworks": [],
        "minimumSystemVersion": "10.15",
        "signingIdentity": null
      },
      "linux": {
        "deb": {
          "depends": ["libgtk-3-0", "libwebkit2gtk-4.0-37"]
        },
        "appimage": {
          "bundleMediaFramework": true
        }
      }
    },
    "security": {
      "csp": "default-src 'self'; script-src 'self'"
    }
  }
}

4.2 平台特定代码

// src-tauri/src/main.rs

#[cfg(target_os = "windows")]
fn platform_init() {
    // Windows特定初始化
    use windows::Win32::System::Console::SetConsoleOutputCP;
    unsafe { SetConsoleOutputCP(65001); }  // UTF-8支持
}

#[cfg(target_os = "macos")]
fn platform_init() {
    // macOS特定初始化
    // 处理Dock、菜单栏等
}

#[cfg(target_os = "linux")]
fn platform_init() {
    // Linux特定初始化
    // 处理DBus、系统托盘等
}

fn main() {
    platform_init();

    tauri::Builder::default()
        .run(tauri::generate_context!())
        .expect("运行tauri应用程序时出错");
}

4.3 GitHub Actions构建矩阵

name: 构建

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: windows-latest
            args: ''
            target: x86_64-pc-windows-msvc
          - platform: macos-latest
            args: '--target x86_64-apple-darwin'
            target: x86_64-apple-darwin
          - platform: macos-latest
            args: '--target aarch64-apple-darwin'
            target: aarch64-apple-darwin
          - platform: ubuntu-22.04
            args: ''
            target: x86_64-unknown-linux-gnu

    runs-on: ${{ matrix.platform }}

    steps:
      - uses: actions/checkout@v4

      - name: 设置Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}

      - name: 安装Linux依赖
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libgtk-3-dev \
            libwebkit2gtk-4.0-dev \
            libappindicator3-dev \
            librsvg2-dev \
            patchelf

      - name: 设置Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 构建
        run: npm run tauri build -- ${{ matrix.args }}

      - name: 上传制品
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.target }}
          path: |
            src-tauri/target/${{ matrix.target }}/release/bundle/

4.4 代码签名配置

Windows (tauri.conf.json):

{
  "tauri": {
    "bundle": {
      "windows": {
        "certificateThumbprint": "YOUR_CERT_THUMBPRINT",
        "digestAlgorithm": "sha256",
        "timestampUrl": "http://timestamp.digicert.com"
      }
    }
  }
}

macOS (tauri.conf.json):

{
  "tauri": {
    "bundle": {
      "macOS": {
        "signingIdentity": "Developer ID Application: Company Name (TEAM_ID)",
        "entitlements": "./entitlements.plist"
      }
    }
  }
}

macOS权益 (entitlements.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
</dict>
</plist>

---

5. 安全标准

5.1 代码签名要求

平台	证书类型	目的
Windows	EV代码签名	立即获得SmartScreen信任
Windows	标准代码签名	信誉后信任
macOS	开发者ID应用	App Store外分发
macOS	开发者ID安装器	签名PKG安装器
Linux	GPG密钥	包签名

5.2 签名最佳实践

# Windows: 验证签名
signtool verify /pa /v MyApp.exe

# macOS: 验证签名
codesign --verify --deep --strict MyApp.app
spctl --assess --type execute MyApp.app

# macOS: 检查公证
xcrun stapler validate MyApp.app

5.3 构建安全

• [ ] 证书存储在CI/CD密钥中，不在仓库中
• [ ] 签名仅在标记版本时进行
• [ ] 构建环境干净/临时
• [ ] 依赖固定并验证
• [ ] 签名后对制品进行校验

---

6. 实现工作流 (TDD)

步骤 1: 先编写失败测试

// tests/build_config_test.rs
#[cfg(test)]
mod tests {
    use std::path::Path;
    use std::process::Command;

    #[test]
    fn test_tauri_config_exists() {
        assert!(Path::new("src-tauri/tauri.conf.json").exists());
    }

    #[test]
    fn test_icons_all_platforms() {
        let required_icons = vec![
            "icons/icon.ico",      // Windows
            "icons/icon.icns",     // macOS
            "icons/icon.png",      // Linux
        ];
        for icon in required_icons {
            assert!(Path::new(&format!("src-tauri/{}", icon)).exists(),
                "缺少图标: {}", icon);
        }
    }

    #[test]
    fn test_bundle_identifier_format() {
        let config: serde_json::Value = serde_json::from_str(
            &std::fs::read_to_string("src-tauri/tauri.conf.json").unwrap()
        ).unwrap();
        let identifier = config["tauri"]["bundle"]["identifier"].as_str().unwrap();
        assert!(identifier.contains('.'), "包ID必须使用反向域名");
    }

    #[test]
    fn test_frontend_builds_successfully() {
        let output = Command::new("npm")
            .args(["run", "build"])
            .output()
            .expect("运行构建失败");
        assert!(output.status.success(), "前端构建失败");
    }
}

步骤 2: 实现最小值以通过

// 创建最小tauri.conf.json
{
  "package": { "productName": "MyApp", "version": "0.1.0" },
  "tauri": {
    "bundle": {
      "identifier": "com.company.myapp",
      "icon": ["icons/icon.ico", "icons/icon.icns", "icons/icon.png"]
    }
  }
}

步骤 3: 重构和扩展

添加平台特定测试以扩展配置：

#[test]
fn test_windows_signing_config() {
    let config: serde_json::Value = serde_json::from_str(
        &std::fs::read_to_string("src-tauri/tauri.conf.json").unwrap()
    ).unwrap();
    let windows = &config["tauri"]["bundle"]["windows"];
    assert!(windows["timestampUrl"].as_str().is_some());
}

#[test]
fn test_macos_minimum_version() {
    let config: serde_json::Value = serde_json::from_str(
        &std::fs::read_to_string("src-tauri/tauri.conf.json").unwrap()
    ).unwrap();
    let min_ver = config["tauri"]["bundle"]["macOS"]["minimumSystemVersion"]
        .as_str().unwrap();
    assert!(min_ver >= "10.15", "必须支持macOS 10.15+");
}

步骤 4: 运行完整验证

# 运行所有构建测试
cargo test --manifest-path src-tauri/Cargo.toml

# 验证所有平台上的构建 (CI)
npm run tauri build -- --target x86_64-pc-windows-msvc
npm run tauri build -- --target x86_64-apple-darwin
npm run tauri build -- --target x86_64-unknown-linux-gnu

# 验证签名
signtool verify /pa target/release/bundle/msi/*.msi
codesign --verify --deep target/release/bundle/macos/*.app

---

7. 性能模式

7.1 增量构建

# Cargo.toml - 启用增量编译
[profile.dev]
incremental = true

[profile.release]
incremental = true
lto = "thin"  # 比 "fat" LTO更快

好: 增量构建重用编译制品

# 首次构建: 2-3分钟
cargo build --release
# 后续构建: 10-30秒
cargo build --release

坏: 每次都干净构建

cargo clean && cargo build --release  # 总是慢

7.2 构建缓存

好: 在CI中缓存Rust依赖

- name: 缓存Cargo
  uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

坏: 无缓存 - 每次构建都下载依赖

- name: 构建
  run: cargo build --release  # 下载所有内容

7.3 并行编译

好: 最大化并行作业

# .cargo/config.toml
[build]
jobs = 8  # 匹配CPU核心

[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "link-arg=-fuse-ld=mold"]  # 快速链接器

坏: 单线程编译

cargo build -j 1  # 极慢

7.4 树摇和死代码消除

好: 启用LTO以减小二进制文件

[profile.release]
lto = true
codegen-units = 1
panic = "abort"
strip = true

坏: 发布版本中的调试符号

[profile.release]
debug = true  # 膨胀二进制大小

7.5 代码分割 (前端)

好: 延迟加载路由

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    treeshakeClientOnly: true
  },
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            'vendor': ['vue', 'pinia'],
            'three': ['three', '@tresjs/core']
          }
        }
      }
    }
  }
})

坏: 捆绑所有内容

// 单一巨大捆绑
import * as everything from './all-modules'

7.6 构建大小优化

好: 分析并优化包

# 分析Rust二进制文件
cargo bloat --release --crates

# 分析前端包
npx nuxi analyze

坏: 忽略包大小

npm run build  # 从不检查包含内容

---

8. 常见错误与反模式

8.1 硬编码路径

// 错误: Windows风格路径
let config = std::fs::read("C:\\Users\\app\\config.json")?;

// 错误: Unix风格绝对路径
let config = std::fs::read("/home/user/.config/app/config.json")?;

// 正确: 平台适当路径
use directories::ProjectDirs;

let dirs = ProjectDirs::from("com", "company", "app")
    .expect("获取项目目录失败");
let config_path = dirs.config_dir().join("config.json");
let config = std::fs::read(config_path)?;

8.2 缺少平台依赖

# 错误: 缺少Linux依赖
- name: 构建
  run: npm run tauri build  # 在Linux上失败!

# 正确: 安装平台依赖
- name: 安装依赖 (Linux)
  if: matrix.platform == 'ubuntu-22.04'
  run: |
    sudo apt-get update
    sudo apt-get install -y \
      libgtk-3-dev \
      libwebkit2gtk-4.0-dev \
      libappindicator3-dev

8.3 通用二进制问题

# 错误: 构建通用二进制而无两个目标
- name: 构建macOS通用二进制
  run: npm run tauri build -- --target universal-apple-darwin
  # 如果x86_64或aarch64不可用则失败!

# 正确: 分别构建每个架构
- name: 构建macOS Intel
  run: npm run tauri build -- --target x86_64-apple-darwin

- name: 构建macOS ARM
  run: npm run tauri build -- --target aarch64-apple-darwin

- name: 创建通用二进制
  run: |
    lipo -create \
      target/x86_64-apple-darwin/release/myapp \
      target/aarch64-apple-darwin/release/myapp \
      -output target/universal/myapp

8.4 缺少公证

# 错误: 签名而无公证
codesign --sign "Developer ID" MyApp.app
# 用户获得Gatekeeper警告!

# 正确: 签名并公证
codesign --sign "Developer ID" --options runtime MyApp.app
xcrun notarytool submit MyApp.zip --apple-id "$APPLE_ID" --password "$APP_PASSWORD" --team-id "$TEAM_ID" --wait
xcrun stapler staple MyApp.app

---

13. 预实施清单

阶段 1: 编写代码前

• [ ] 阅读所有平台特定要求
• [ ] 识别目标平台和架构
• [ ] 编写构建配置验证测试
• [ ] 为所有目标设置CI/CD矩阵
• [ ] 获取代码签名证书
• [ ] 在CI环境中配置密钥

阶段 2: 实施期间

• [ ] 每次配置更改后运行测试
• [ ] 验证增量构建工作
• [ ] 测试平台特定代码与条件编译
• [ ] 添加依赖后检查包大小
• [ ] 验证所有平台的图标存在
• [ ] 在实际目标平台上测试 (不仅CI)

阶段 3: 提交前

• [ ] 所有构建配置测试通过
• [ ] Windows证书是EV或已建立信誉
• [ ] macOS应用使用开发者ID签名
• [ ] macOS应用已公证和钉住
• [ ] Linux包使用GPG签名
• [ ] 所有签名使用时间戳
• [ ] 签名凭据仅在CI密钥中
• [ ] 构建制品有校验
• [ ] 依赖固定
• [ ] 构建日志不暴露密钥
• [ ] Windows SmartScreen通过
• [ ] macOS Gatekeeper通过
• [ ] 安装器在干净系统上测试
• [ ] 自动更新URL是HTTPS

---

14. 总结

您的目标是创建跨平台构建，这些构建是：

• 正确签名: 被每个操作系统信任
• 平台原生: 尊重每个平台的惯例
• 优化: 合理的文件大小、快速启动

您理解跨平台开发需要：

1. 在每个目标平台上测试 (不仅您的开发机器)
2. 正确的代码签名以获得用户信任
3. 平台特定配置和依赖
4. 了解分发要求

构建提醒: 始终在发布前在每个平台上测试。始终签名您的版本。始终验证签名工作正确。如有疑问，请参阅 references/security-examples.md 以获取签名程序。