wormhole-client/docs/BUILD_DMG.md

# macOS DMG 安装包构建指南

本文档介绍如何为 Wormhole SOCKS5 Client 构建 macOS DMG 安装包。

## 🔧 环境要求

### 系统要求
- **macOS 10.13+** (High Sierra 或更高版本)
- **Xcode Command Line Tools** 或完整的 Xcode
- **Go 1.19+**

### 可选工具
- **Python 3** + **Pillow (PIL)** - 用于生成自定义应用图标
- **Git** - 用于版本控制

## 🚀 快速开始

### 一键构建
```bash
# 构建完整的 DMG 安装包
make dmg

# 或者使用完整命令
make dmg-macos
```

### 分步构建
```bash
# 1. 构建 macOS 应用程序包
./scripts/build-macos.sh

# 2. 创建 DMG 安装包
./scripts/create-dmg.sh

# 3. 验证和测试
open build/Wormhole-Client-v1.0.0.dmg
```

## 📁 构建产物

构建成功后，将在 `build/` 目录下生成以下文件：

```
build/
├── Wormhole Client.app/          # macOS 应用程序包
│   ├── Contents/
│   │   ├── Info.plist            # 应用信息
│   │   ├── MacOS/
│   │   │   ├── wormhole-client   # 二进制文件
│   │   │   └── Wormhole Client   # 启动脚本
│   │   └── Resources/
│   │       ├── configs/          # 配置文件
│   │       └── app.icns         # 应用图标
│   └── ...
└── Wormhole-Client-v1.0.0.dmg    # 最终安装包
```

## 🎨 自定义图标

### 使用自定义图标
1. 准备一个 1024x1024 的 PNG 图片
2. 将其保存为 `assets/icons/icon.png`
3. 重新构建即可使用自定义图标

### 自动生成图标
如果没有自定义图标，构建脚本会自动：
1. 尝试使用 Python PIL 生成简单图标
2. 如果失败，使用系统默认应用图标

## 📦 DMG 特性

### 安装体验
- **拖拽安装**: 用户只需将 app 拖到 Applications 文件夹
- **自动布局**: 优化的窗口布局和图标位置
- **说明文档**: 包含安装和使用说明

### DMG 内容
- `Wormhole Client.app` - 主应用程序
- `Applications` - Applications 文件夹快捷方式
- `README.txt` - 安装和使用说明

## 🔍 构建脚本详解

### build-macos.sh
- 编译 Go 二进制文件 (amd64 架构)
- 创建标准的 macOS 应用程序包结构
- 复制配置文件和资源
- 生成或复制应用图标
- 创建 Info.plist 文件
- 设置启动脚本

### create-dmg.sh
- 创建临时 DMG 工作目录
- 复制应用程序和创建符号链接
- 生成说明文档
- 使用 AppleScript 美化 DMG 外观
- 创建压缩的只读 DMG
- 验证 DMG 完整性

### build-dmg.sh
- 一键执行完整构建流程
- 环境检查和工具验证
- 构建结果汇总和验证

## 🛠️ 故障排除

### 常见问题

#### 1. hdiutil 权限错误
```bash
# 解决方案：使用 sudo 或给予磁盘访问权限
sudo ./scripts/create-dmg.sh
```

#### 2. AppleScript 执行失败
```bash
# 检查系统完整性保护 (SIP)
csrutil status

# 在系统偏好设置中允许自动化权限
# 系统偏好设置 > 安全性与隐私 > 隐私 > 自动化
```

#### 3. Go 编译失败
```bash
# 检查 Go 版本
go version

# 确保依赖已下载
go mod download
go mod tidy
```

### 调试模式
```bash
# 开启详细输出
set -x
./scripts/build-dmg.sh
```

## 📱 应用程序使用

### 安装后使用
1. 双击 DMG 文件挂载
2. 拖拽 `Wormhole Client.app` 到 Applications
3. 从 Applications 或 Launchpad 启动应用

### 启动模式
- **双击启动**: 自动以 HTTP 模式启动并打开 Web 界面
- **终端启动**: 支持所有命令行参数
  ```bash
  # HTTP 模式
  /Applications/Wormhole\ Client.app/Contents/MacOS/Wormhole\ Client -mode http
  
  # 全局模式 (需要 sudo)
  sudo /Applications/Wormhole\ Client.app/Contents/MacOS/Wormhole\ Client -mode global
  ```

### Web 界面
- **管理界面**: http://127.0.0.1:8080/gui
- **统计信息**: http://127.0.0.1:8080/stats
- **健康检查**: http://127.0.0.1:8080/health

## 🔒 代码签名 (可选)

如果需要分发给其他用户，建议进行代码签名：

```bash
# 签名应用程序
codesign --force --deep --sign "Developer ID Application: Your Name" \
    "build/Wormhole Client.app"

# 签名 DMG
codesign --force --sign "Developer ID Application: Your Name" \
    "build/Wormhole-Client-v1.0.0.dmg"

# 验证签名
codesign --verify --deep --strict --verbose=2 "build/Wormhole Client.app"
spctl --assess --type execute --verbose "build/Wormhole Client.app"
```

## 📈 版本管理

修改版本号：
1. 编辑 `scripts/build-macos.sh` 中的 `VERSION` 变量
2. 编辑 `Makefile` 中的 `VERSION` 变量
3. 重新构建 DMG

## 🤝 贡献

如果您发现构建脚本的问题或有改进建议，欢迎提交 Issue 或 Pull Request。

## 📄 许可证

本构建系统遵循项目的 MIT 许可证。