4.7 KiB

Raw Blame History Unescape Escape

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 - 用于版本控制

🚀 快速开始

一键构建

# 构建完整的 DMG 安装包
make dmg

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

分步构建

# 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    # 最终安装包

🎨 自定义图标

使用自定义图标

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

自动生成图标

如果没有自定义图标，构建脚本会自动：

尝试使用 Python PIL 生成简单图标
如果失败，使用系统默认应用图标

📦 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 权限错误

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

2. AppleScript 执行失败

# 检查系统完整性保护 (SIP)
csrutil status

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

3. Go 编译失败

# 检查 Go 版本
go version

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

调试模式

# 开启详细输出
set -x
./scripts/build-dmg.sh

📱 应用程序使用

安装后使用

双击 DMG 文件挂载
拖拽 Wormhole Client.app 到 Applications
从 Applications 或 Launchpad 启动应用

启动模式

双击启动: 自动以 HTTP 模式启动并打开 Web 界面

终端启动: 支持所有命令行参数

# 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

🔒 代码签名 (可选)

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

# 签名应用程序
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"

📈 版本管理

修改版本号：

编辑 scripts/build-macos.sh 中的 VERSION 变量
编辑 Makefile 中的 VERSION 变量
重新构建 DMG

🤝 贡献

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

📄 许可证

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

4.7 KiB Raw Blame History Unescape Escape