多平台构建与打包
本页说明 wssocks-plugin-ustb 当前仓库中由根目录 Makefile 定义的多平台构建矩阵、产物命名、构建参数与清理行为，并补充 README 对客户端平台支持和发布下载命名的约定。
Purpose and Scope
本页面向需要本地构建、验证或发布 CLI 客户端的开发者和维护者，覆盖：
Makefile的默认构建目标all；- Linux、macOS、Windows 三个平台的目标架构与输出文件名；
CGO_ENABLED=0、GOOS、GOARCH和--trimpath的实际作用边界；- README 中对 CLI、GUI 和 SwiftUI 客户端的平台支持及下载命名的说明；
clean目标删除哪些构建产物。
本页不展开 wssocks 协议、VPN 登录流程、GUI/SwiftUI 的业务实现，也不推断仓库中未被当前构建文件声明的 CI 发布步骤。关于客户端使用方式，参见仓库 README 和项目文档；关于版本历史，参见 CHANGELOG。
Overview
该项目将 CLI 入口包固定为 github.com/genshen/wssocks-plugin-ustb/wssocks-ustb。根目录 Makefile 通过四个显式目标生成四类二进制：Linux x86-64、Linux ARM64、macOS x86-64 和 Windows x86-64。all 目标依赖这四个目标，因此执行 make all 会按 Make 的依赖关系确保这些文件均被构建；每个目标都使用独立的 GOOS/GOARCH 环境变量，而不是依赖当前宿主机平台。
构建策略的关键点是：
- 目标平台显式化：
GOOS和GOARCH直接写在目标命令中，产物名称也包含平台和架构，避免不同平台产物混淆。 - 禁用 CGO：四个发布目标都设置
CGO_ENABLED=0，使构建命令明确采用无 CGO 配置。源代码没有进一步声明原生库打包或交叉编译器要求，因此本页不对外部工具链做额外假设。 - 可复现路径信息：公共变量
FLAGS=--trimpath被传给go build，用于从构建结果中移除本地路径信息。 - CLI 与 GUI 的边界：README 将 CLI、基于 Fyne 的
client-ui和 macOS 原生swiftui-client分开描述；根目录Makefile只直接列出 CLI 包的四个构建目标。
Architecture
图中的依赖是构建文件中明确表达的关系：all 依赖四个平台目标；每个平台目标使用相同的 FLAGS 和 PACKAGE，但设置不同的目标操作系统、架构和输出路径。README 则提供这些 CLI 产物面向用户的下载命名约定，并把它们与 GUI 客户端、SwiftUI 客户端区分开。
构建矩阵与实现细节
公共变量和入口包
Makefile 在顶层定义两个公共变量：PACKAGE 指向 CLI 的 Go module package，FLAGS 固定为 --trimpath。四个构建命令都通过 ${PACKAGE} 作为 go build 的包参数，因此平台目标只负责改变编译环境和输出名，不改变源码入口。
1PACKAGE=github.com/genshen/wssocks-plugin-ustb/wssocks-ustb
2
3.PHONY: clean all
4
5FLAGS=--trimpath
6
7# wssocks-ustb:
8#\tgo build -o wssocks-ustbSource: Makefile
注释中的普通宿主机构建命令仅是历史/说明性示例，并不是 all 的依赖目标；实际批量入口是下面定义的四个平台目标。因此，不能从当前 Makefile 得出一个名为 wssocks-ustb 的默认无后缀文件会被 make all 生成。
all 目标与四个平台目标
1all: wssocks-ustb-linux-amd64 wssocks-ustb-linux-arm64 wssocks-ustb-darwin-amd64 wssocks-ustb-windows-amd64.exe
2
3wssocks-ustb-linux-amd64:
4\tCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build ${FLAGS} -o wssocks-ustb-linux-amd64 ${PACKAGE}
5
6wssocks-ustb-linux-arm64:
7\tCGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build ${FLAGS} -o wssocks-ustb-linux-arm64 ${PACKAGE}
8
9wssocks-ustb-darwin-amd64:
10\tCGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build ${FLAGS} -o wssocks-ustb-darwin-amd64 ${PACKAGE}
11
12wssocks-ustb-windows-amd64.exe:
13\tCGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build ${FLAGS} -o wssocks-ustb-windows-amd64.exe ${PACKAGE}Source: Makefile
平台矩阵可以概括为：
| Make 目标 | GOOS | GOARCH | CGO_ENABLED | 输出文件 |
|---|---|---|---|---|
wssocks-ustb-linux-amd64 | linux | amd64 | 0 | wssocks-ustb-linux-amd64 |
wssocks-ustb-linux-arm64 | linux | arm64 | 0 | wssocks-ustb-linux-arm64 |
wssocks-ustb-darwin-amd64 | darwin | amd64 | 0 | wssocks-ustb-darwin-amd64 |
wssocks-ustb-windows-amd64.exe | windows | amd64 | 0 | wssocks-ustb-windows-amd64.exe |
仓库 go.mod 声明使用 Go 1.24，并指定 toolchain go1.24.10。因此构建环境至少需要能够解析该 module 的 Go 版本要求；Makefile 本身没有封装 Go 版本检查或依赖下载步骤。
单目标构建和批量构建
开发者可以选择直接构建单个平台目标，以便快速验证某一产物；也可以执行 all，让 Make 根据依赖关系构建完整矩阵。以下命令形式来自实际目标名称和 README 的 CLI 安装说明：
make wssocks-ustb-linux-amd64
make allSource: Makefile
Makefile 没有为 all 声明 .PHONY，但 all 与 clean 被列在 .PHONY 中，因此 make all 不会因为同名文件而被当作已完成目标。四个平台目标自身没有 .PHONY 声明；它们以对应输出文件作为目标名，Make 可以利用输出文件时间戳避免不必要的重复构建。这个行为是由目标名与输出文件名相同这一事实直接形成的。
Core Flow
Source: Makefile
实际控制流可以按以下顺序理解：
- Make 接收
all或某个具体目标。all将四个产物目标作为依赖；单目标命令只选择一个平台。 - Make 执行目标行内的环境变量赋值。赋值只作用于该次
go build，不会修改调用者的全局 shell 环境。 go build接收公共--trimpath参数、平台专属的-o输出文件名和固定的PACKAGE包路径。- 成功后，输出文件直接位于仓库根目录，文件名同时承担 Make 目标名和产物标识的作用。
当前源码没有显示重试、缓存、签名、压缩、归档或校验和生成逻辑；这些步骤不能作为本 Makefile 的既有行为记录。
客户端平台与发布命名约定
README 将客户端分成三类：命令行 cli、基于 Fyne 的 client-ui，以及 macOS 原生 swiftui-client。其中 CLI 的支持平台比根目录 Makefile 的四项目标更宽：README 还列出 macOS arm64，但当前 Makefile 只定义 macOS amd64 目标。因此，macOS arm64 的构建入口或发布实现不在本页已读取的根目录 Makefile 中，不能把它误写成现有 Make 目标。
- cli: command line client.
- client-ui: From v0.5.0, we also provide a GUI client for windows and macos.
- swiftui-client: From v0.6.0 and v0.7.0, we also provide a mac native app.Source: README.md
README 给出的客户端平台表为：
| 客户端 | README 声明的平台 |
|---|---|
| CLI | Windows x64、macOS x64/arm64、Linux x64/arm64 |
client-ui | Windows x64、macOS x64/arm64 |
swiftui-client | macOS x64/arm64 |
CLI 下载文件使用 wssocks-ustb-$OS-$ARCH 形式；Windows 的实际 Make 产物额外带 .exe 后缀。GUI 客户端则使用 client-ui-$OS-$ARCH 命名。SwiftUI 应用使用 wssocks-ustb-client-macOS-*.app.zip 形式。README 也明确指出，CLI 和 client-ui 客户端均包含 wssocks 与该插件。
go get -u github.com/genshen/wssocks-plugin-ustb/wssocks-ustb
wssocks-ustb --helpSource: README.md
配置与命令参考
构建配置
| 配置/变量 | 类型 | 默认值或实际值 | 说明 |
|---|---|---|---|
PACKAGE | Make 变量 | github.com/genshen/wssocks-plugin-ustb/wssocks-ustb | 传给 go build 的 CLI 包路径 |
FLAGS | Make 变量 | --trimpath | 所有四个平台构建共用的 Go 构建参数 |
CGO_ENABLED | Go 构建环境变量 | 0 | 四个平台目标均禁用 CGO |
GOOS | Go 构建环境变量 | 按目标为 linux、darwin 或 windows | 决定目标操作系统 |
GOARCH | Go 构建环境变量 | 按目标为 amd64 或 arm64 | 决定目标 CPU 架构 |
-o | go build 参数 | 各目标的产物名 | 决定输出文件名和根目录位置 |
这些值全部来自 Makefile；没有发现 .env、YAML 或其他构建配置覆盖机制。go.mod 另外声明 Go module 版本为 go 1.24，工具链为 go1.24.10，这属于 Go 模块工具链要求，而不是 Make 变量。
常用命令
| 命令 | 用途 | 结果 |
|---|---|---|
make all | 构建当前 Makefile 声明的完整 CLI 矩阵 | 生成四个目标文件 |
make wssocks-ustb-linux-amd64 | 只构建 Linux x86-64 | 生成 Linux amd64 CLI |
make wssocks-ustb-linux-arm64 | 只构建 Linux ARM64 | 生成 Linux arm64 CLI |
make wssocks-ustb-darwin-amd64 | 只构建 macOS x86-64 | 生成 Darwin amd64 CLI |
make wssocks-ustb-windows-amd64.exe | 只构建 Windows x86-64 | 生成带 .exe 后缀的 CLI |
make clean | 删除 Makefile 管理的四个平台文件 | 不删除源码或 Go module 缓存 |
清理、失败模式与边界条件
清理行为
1.PHONY: clean all
2
3clean:
4\trm -f wssocks-ustb-linux-amd64 wssocks-ustb-linux-arm64 wssocks-ustb-darwin-amd64 wssocks-ustb-windows-amd64.exerm -f 使不存在的产物不会因为“文件不存在”而导致清理命令失败。清理列表与 all 的四个输出一一对应；仓库中其他客户端文件、归档文件、校验和和发布目录不在这条命令的删除范围内。
可观察的失败条件
源代码只提供 Make 规则，没有包装错误处理。因此，当 go build 失败时，Make 会将该命令的非零退出状态传递给构建流程；当前 Makefile 没有重试、降级目标或错误转换逻辑。根据已读取的配置，可以明确检查以下条件：
- Go 工具链无法满足
go.mod的go 1.24/toolchain go1.24.10要求时，构建可能在 Go 命令阶段失败； PACKAGE无法解析、依赖无法获取或源码编译失败时，目标不会产生可用二进制；- 设置
CGO_ENABLED=0后，如果目标包或其依赖要求 CGO，失败会由go build直接报告； - 目标文件已经存在时，Make 可能依据文件时间戳跳过对应目标；执行
make clean后再make all可显式重建四项。
上述依赖或工具链失败的具体错误文本不在仓库源文件中，因此本页不虚构错误类型或日志格式。
并发与一致性
Makefile 没有声明并发锁、临时文件或原子发布步骤。每个平台目标写入不同的输出文件名，所以从规则本身看，四个目标之间没有共享输出路径；但源码没有提供 CI 并行策略，也没有证明并行执行时依赖下载或外部缓存的行为。发布系统若需要“全部成功后再对外暴露”的一致性，应在本 Makefile 之外实现。
性能与运维注意事项
--trimpath主要影响构建结果中的路径信息，不等于压缩、优化或去除调试符号；Makefile 没有提供-ldflags、压缩器或归档器配置。CGO_ENABLED=0明确了四个目标的构建开关，但 README 的平台支持表比 Makefile 更宽，尤其是 macOS arm64；发布前应核对实际产物，而不能仅凭 README 的平台表假定 Make 已覆盖全部平台。- 产物直接写入仓库根目录。执行多次不同目标构建时，依靠平台/架构命名避免覆盖；Windows 目标通过
.exe后缀保持平台惯例。 - README 提供 GitHub Releases 和 OSDN night release 的下载入口，但当前已读取的 Makefile 没有自动上传、签名或生成 release 资产的规则。发布自动化的具体实现细节未在本页证据范围内找到。
Extension Points
当前最直接的扩展点是为新的 GOOS/GOARCH 增加一个与既有目标相同形态的 Make 规则，并把它加入 all 和 clean 的文件列表。扩展时需要同时保持三处一致：目标名、-o 输出名、清理文件名。README 的下载命名和平台支持表也应同步更新，否则构建矩阵与用户可下载文件说明会出现偏差。
不过，当前 Makefile 没有抽象出平台列表、模板规则、版本注入变量或发布归档目标；因此不能把这些机制当成现有可配置扩展点。若要引入它们，应先验证与当前“每个平台显式目标”的可读性和产物命名兼容性。
Tests
在本次源文件发现结果中没有找到测试文件或构建测试脚本。已读取的 Makefile 也没有 test、vet、lint 或构建后 smoke-test 目标。因此可以记录的验证方式仅限于：执行目标并检查 go build 的退出结果，以及确认对应输出文件名是否生成；运行时 CLI 行为需要由项目其他测试或人工验证流程覆盖。
API Reference
本页主题是 Make/Go 构建流程，不提供 Go 服务 API 或 HTTP endpoint。可作为构建接口使用的目标如下：
all：无参数；依赖四个平台 CLI 目标。wssocks-ustb-linux-amd64：无参数；生成 Linux amd64 CLI。wssocks-ustb-linux-arm64：无参数；生成 Linux arm64 CLI。wssocks-ustb-darwin-amd64：无参数；生成 Darwin amd64 CLI。wssocks-ustb-windows-amd64.exe：无参数；生成 Windows amd64 CLI。clean：无参数；使用rm -f删除四个 Makefile 管理的 CLI 产物。
这些目标没有自定义参数校验、返回值对象或异常类型；失败由 Make 和底层 go build 的进程退出状态表达。
Related Links
- 项目 README：项目定位、客户端类型、支持平台和下载命名。
- Makefile：构建矩阵、公共参数和清理目标。
- go.mod：Go module、Go 版本和直接依赖声明。
- CHANGELOG.md：版本发布、编译修复和客户端相关变更记录。