feat: 完善Android报错

Author: Wayne

README.md

@@ -73,6 +73,12 @@ Build a macOS `.app` bundle and `.dmg` with Simdock icons:
 ./scripts/package-macos.sh
 ```
 
+Build a macOS `.pkg` installer:
+
+```bash
+./scripts/package-macos-pkg.sh
+```
+
 ## Project Layout
 
 ```text
@@ -92,6 +98,8 @@ scripts/
   run-desktop.sh      Desktop development runner.
   build-release.sh    Release build helper.
   package-macos.sh    macOS app bundle and DMG packaging helper.
+  package-macos-pkg.sh
+                      macOS PKG installer packaging helper.
   size-report.sh      Release binary size helper.
 ```
 

README.zh-CN.md

@@ -73,6 +73,12 @@ Simdock是一个仅面向macOS的开源工具，用Rust构建，提供桌面应
 ./scripts/package-macos.sh
 ```
 
+构建macOS`.pkg`安装包：
+
+```bash
+./scripts/package-macos-pkg.sh
+```
+
 ## 项目结构
 
 - `apps/simdock-cli/`：命令行应用。
@@ -87,6 +93,7 @@ Simdock是一个仅面向macOS的开源工具，用Rust构建，提供桌面应
 - `scripts/run-desktop.sh`：桌面端开发运行脚本。
 - `scripts/build-release.sh`：release构建脚本。
 - `scripts/package-macos.sh`：macOS app bundle和DMG打包脚本。
+- `scripts/package-macos-pkg.sh`：macOS PKG安装包打包脚本。
 - `scripts/size-report.sh`：release体积报告脚本。
 
 ## 文档

crates/simdock-core/src/provider/android.rs

@@ -1,5 +1,7 @@
 use std::{
-    env, fs,
+    env,
+    ffi::OsString,
+    fs,
     path::{Path, PathBuf},
     process::Stdio,
 };
@@ -25,6 +27,8 @@ const ANDROID_CMDLINE_TOOLS_ARCHIVE: &str = "commandlinetools-mac-14742923_lates
 const MANAGED_JAVA_FEATURE_VERSION: u16 = 21;
 const SDKMANAGER_LICENSE_INPUT_REPEATS: usize = 200;
 
+type ToolEnv = (&'static str, OsString);
+
 #[derive(Debug, Clone)]
 /// Android Emulator平台Provider。
 ///
@@ -745,24 +749,33 @@ fn parse_java_major_version(version: &str) -> Option<u16> {
 }
 
 /// Android SDK工具运行时需要的一组环境变量。
-fn android_tool_envs<'a>(
-    sdk_root: &'a Path,
-    avd_root: &'a Path,
-    java_runtime: &'a JavaRuntime,
-) -> Vec<(&'static str, &'a Path)> {
+fn android_tool_envs(sdk_root: &Path, avd_root: &Path, java_runtime: &JavaRuntime) -> Vec<ToolEnv> {
     let mut envs = vec![
-        ("ANDROID_SDK_ROOT", sdk_root),
-        ("ANDROID_HOME", sdk_root),
-        ("ANDROID_AVD_HOME", avd_root),
+        ("ANDROID_SDK_ROOT", sdk_root.as_os_str().to_os_string()),
+        ("ANDROID_HOME", sdk_root.as_os_str().to_os_string()),
+        ("ANDROID_AVD_HOME", avd_root.as_os_str().to_os_string()),
     ];
 
     if let Some(java_home) = java_runtime.managed_home() {
-        envs.push(("JAVA_HOME", java_home));
+        let java_binary = JavaRuntime::managed_java_binary(java_home);
+        envs.push(("JAVA_HOME", java_home.as_os_str().to_os_string()));
+        envs.push(("JAVACMD", java_binary.as_os_str().to_os_string()));
+        envs.push(("PATH", prepend_to_path_env(&java_home.join("bin"))));
     }
 
     envs
 }
 
+/// 把托管JRE的`bin`放到PATH最前面，兜底兼容只查找`java`的SDK脚本。
+fn prepend_to_path_env(path: &Path) -> OsString {
+    let mut paths = vec![path.to_path_buf()];
+    if let Some(current_path) = env::var_os("PATH") {
+        paths.extend(env::split_paths(&current_path));
+    }
+
+    env::join_paths(paths).unwrap_or_else(|_| path.as_os_str().to_os_string())
+}
+
 /// 确保Android SDK工具可用的Java运行时存在。
 ///
 /// 优先复用系统Java；如果系统没有Java，就下载轻量JRE到Simdock
@@ -902,7 +915,11 @@ async fn ensure_android_java_runtime(
     let _ = fs::remove_dir_all(&extract_dir);
 
     let Some((runtime, summary)) = probe_managed_java(java_root).await else {
-        bail!("Managed Java runtime was extracted but java -version failed");
+        let java_binary = JavaRuntime::managed_java_binary(java_root);
+        bail!(
+            "Managed Java runtime was extracted but {} could not run. Remove the managed Java runtime from Manage installed content and run one-click install again. If this is a company-managed Mac, ask IT to allow executing this binary.",
+            java_binary.display()
+        );
     };
     emit_log(
         sender,
@@ -1095,7 +1112,10 @@ async fn accept_android_licenses(
     if probe.success {
         Ok(())
     } else {
-        bail!("Android SDK license acceptance failed: {}", probe.summary())
+        bail!(
+            "Android SDK license acceptance failed: {}",
+            android_tool_failure_summary("sdkmanager", &probe, Some(java_runtime))
+        )
     }
 }
 
@@ -1127,7 +1147,7 @@ async fn install_android_packages(
     } else {
         bail!(
             "sdkmanager package installation failed: {}",
-            probe.summary()
+            android_tool_failure_summary("sdkmanager", &probe, Some(java_runtime))
         )
     }
 }
@@ -1225,13 +1245,13 @@ async fn ensure_android_avd(
 
         bail!(
             "avdmanager failed to create Android virtual device: {}",
-            fallback_probe.summary()
+            android_tool_failure_summary("avdmanager", &fallback_probe, Some(java_runtime))
         );
     }
 
     bail!(
         "avdmanager failed to create Android virtual device: {}",
-        create_probe.summary()
+        android_tool_failure_summary("avdmanager", &create_probe, Some(java_runtime))
     )
 }
 
@@ -1253,7 +1273,7 @@ async fn tool_check(
     name: &str,
     path: Option<PathBuf>,
     args: &[&str],
-    envs: &[(&str, &Path)],
+    envs: &[ToolEnv],
 ) -> DoctorCheck {
     match path {
         Some(path) => {
@@ -1268,7 +1288,7 @@ async fn tool_check(
                 format!(
                     "{name} probe failed at {}: {}",
                     path.display(),
-                    probe.summary()
+                    android_tool_failure_summary(name, &probe, None)
                 )
             };
 
@@ -1286,6 +1306,41 @@ async fn tool_check(
     }
 }
 
+/// 把Android工具里常见的Java定位失败转换成可执行的修复说明。
+fn android_tool_failure_summary(
+    tool_name: &str,
+    probe: &CommandProbe,
+    java_runtime: Option<&JavaRuntime>,
+) -> String {
+    let summary = probe.summary();
+    if !is_android_java_runtime_error(probe) {
+        return summary;
+    }
+
+    let runtime_hint = match java_runtime {
+        Some(JavaRuntime::Managed { java_home }) => format!(
+            "Simdock tried to use managed Java at {}. Remove the managed Java runtime from Manage installed content and run one-click install again. If this is a company-managed Mac, ask IT to allow executing {}.",
+            java_home.display(),
+            JavaRuntime::managed_java_binary(java_home).display()
+        ),
+        _ => "Simdock could not use a Java runtime for Android SDK tools. Run one-click install again so Simdock can provision managed Java. If this is a company-managed Mac, ask IT to allow Simdock's managed Java runtime under ~/Library/Application Support/com.simdock.Simdock/java-runtime.".to_string(),
+    };
+
+    format!(
+        "{tool_name} could not locate or execute Java. {runtime_hint} Original output: {summary}"
+    )
+}
+
+/// 识别macOS和Android命令行工具输出中的Java缺失/不可执行错误。
+fn is_android_java_runtime_error(probe: &CommandProbe) -> bool {
+    let output = format!("{}\n{}", probe.stdout, probe.stderr).to_lowercase();
+    output.contains("unable to locate a java runtime")
+        || output.contains("no java runtime present")
+        || output.contains("could not find java")
+        || output.contains("could not find a valid java")
+        || output.contains("java_home is not defined correctly")
+}
+
 /// 运行PATH中的命令并收集输出。
 async fn run_command(program: &str, args: &[&str]) -> CommandProbe {
     finish_probe({
@@ -1310,13 +1365,13 @@ async fn run_path_command(program: &Path, args: &[&str]) -> CommandProbe {
 async fn run_path_command_with_env(
     program: &Path,
     args: &[&str],
-    envs: &[(&str, &Path)],
+    envs: &[ToolEnv],
 ) -> CommandProbe {
     finish_probe({
         let mut command = Command::new(program);
         command.args(args);
         for (key, value) in envs {
-            command.env(key, value);
+            command.env(*key, value);
         }
         command
     })
@@ -1327,15 +1382,15 @@ async fn run_path_command_with_env(
 async fn run_command_streamed(
     program: &str,
     args: &[String],
-    envs: &[(&str, &Path)],
+    envs: &[ToolEnv],
     task_id: &str,
     sender: Option<&TaskSender>,
 ) -> CommandProbe {
     let mut command = Command::new(program);
     command.args(args);
 
     for (key, value) in envs {
-        command.env(key, value);
+        command.env(*key, value);
     }
 
     finish_probe_streamed(command, program, args, None, task_id, sender).await
@@ -1345,7 +1400,7 @@ async fn run_command_streamed(
 async fn run_path_command_streamed_with_input(
     program: &Path,
     args: &[String],
-    envs: &[(&str, &Path)],
+    envs: &[ToolEnv],
     input: Option<String>,
     task_id: &str,
     sender: Option<&TaskSender>,
@@ -1354,7 +1409,7 @@ async fn run_path_command_streamed_with_input(
     command.args(args);
 
     for (key, value) in envs {
-        command.env(key, value);
+        command.env(*key, value);
     }
 
     let program_label = program.display().to_string();

docs/packaging.md

@@ -28,6 +28,25 @@ The macOS packaging script:
 - Adds a Finder custom icon to the generated `.dmg` file when macOS icon tools are available.
 - Adds an `/Applications` symlink for drag-and-drop installation.
 
+## macOS PKG
+
+```bash
+./scripts/package-macos-pkg.sh
+```
+
+The PKG packaging script:
+
+- Reads the app version from the root `Cargo.toml`.
+- Builds `target/macos/Simdock.app`.
+- Creates `target/macos/Simdock-<version>.pkg`.
+- Installs `Simdock.app` into `/Applications`.
+
+Create a signed installer package by passing a Developer ID Installer identity:
+
+```bash
+PKG_SIGN_IDENTITY="Developer ID Installer: Your Name (TEAMID)" ./scripts/package-macos-pkg.sh
+```
+
 ## Size Report
 
 ```bash

scripts/build-macos-app.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+APP_NAME="Simdock"
+BINARY_NAME="simdock-desktop"
+BUNDLE_ID="com.simdock.Simdock"
+VERSION="$(awk -F '"' '/^version = / { print $2; exit }' "$ROOT_DIR/Cargo.toml")"
+
+OUT_DIR="$ROOT_DIR/target/macos"
+APP_DIR="$OUT_DIR/$APP_NAME.app"
+ICON_SOURCE="$ROOT_DIR/assets/brand/simdock.icns"
+
+if [[ -z "$VERSION" ]]; then
+  echo "Could not read version from Cargo.toml" >&2
+  exit 1
+fi
+
+if [[ ! -f "$ICON_SOURCE" ]]; then
+  echo "Missing macOS icon: $ICON_SOURCE" >&2
+  exit 1
+fi
+
+echo "Building release binary..."
+cargo build --release -p "$BINARY_NAME"
+
+echo "Creating app bundle..."
+rm -rf "$APP_DIR"
+mkdir -p "$APP_DIR/Contents/MacOS" "$APP_DIR/Contents/Resources"
+
+cp "$ROOT_DIR/target/release/$BINARY_NAME" "$APP_DIR/Contents/MacOS/$APP_NAME"
+chmod +x "$APP_DIR/Contents/MacOS/$APP_NAME"
+cp "$ICON_SOURCE" "$APP_DIR/Contents/Resources/$APP_NAME.icns"
+printf 'APPL????' > "$APP_DIR/Contents/PkgInfo"
+
+cat > "$APP_DIR/Contents/Info.plist" <<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>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleDisplayName</key>
+  <string>$APP_NAME</string>
+  <key>CFBundleExecutable</key>
+  <string>$APP_NAME</string>
+  <key>CFBundleIconFile</key>
+  <string>$APP_NAME</string>
+  <key>CFBundleIdentifier</key>
+  <string>$BUNDLE_ID</string>
+  <key>CFBundleName</key>
+  <string>$APP_NAME</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>$VERSION</string>
+  <key>CFBundleVersion</key>
+  <string>$VERSION</string>
+  <key>LSApplicationCategoryType</key>
+  <string>public.app-category.developer-tools</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>13.0</string>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+</dict>
+</plist>
+PLIST
+
+if command -v codesign >/dev/null 2>&1; then
+  echo "Applying ad-hoc code signature..."
+  codesign --force --deep --sign - "$APP_DIR" >/dev/null
+fi
+
+echo "Built app: $APP_DIR"