企业官网建设流程全解析

ShichiZip 是一款面向 macOS 的原生 7-Zip 衍生压缩工具，完整支持上游 7-Zip 的全部压缩格式，并带来一键智能解压、Quick Look 压缩包预览等 Mac 专属体验。本文是一篇面向新手的 ShichiZip 源码编译教程：整个构建流程由 XcodeGen、Zig、Xcode 三个工具接力完成——XcodeGen 生成工程、Zig 编译 7-Zip 核心静态库与 SFX 模块、Xcode 产出最终 App。跟着下面的步骤走一遍，你就能从源码构建出属于自己的 ShichiZip。

一、准备工作：安装 XcodeGen、Zig 和 Xcode

在开始编译前，需要确认本机具备以下 4 个依赖（详见 BUILD.md）：

brew install xcodegen zig

⚠️ 注意：Homebrew 的zig 0.16.0bottle 携带了一个损坏的zig ar，务必升级到0.16.0_1及以上版本，否则会在这一步踩坑。

然后获取源码。仓库通过 Git 子模块管理上游 7-Zip 源码（位于vendor/），clone 时记得带上--recurse-submodules：

git clone --recurse-submodules https://gitcode.com/gh_mirrors/sh/ShichiZip cd ShichiZip

如果之前已经 clone 过但漏了子模块，补一句即可：git submodule update --init --recursive。

ShichiZip 提供两个共享同一份 App 代码、链接不同上游 7-Zip 代码树的变体：

• Mainline（scheme 名ShichiZip）：链接vendor/7zip主线代码；
• Zstandard fork（scheme 名ShichiZipZS）：链接vendor/7zip-zstd分支，额外支持 Zstandard 等压缩算法。

下文命令以 Mainline 为例，Zstandard 版本把 scheme 和-Dvariant换成zs即可。

二、第一步：用 XcodeGen 生成 Xcode 工程

在仓库根目录执行：

xcodegen generate

这一步做三件事（流程说明见 BUILD.md）：

1. 消费入口文件 project.yml，它通过include汇总了project/specs/下的 base、archive-core、apps、quick-actions、schemes 等规格文件，生成ShichiZip.xcodeproj；
2. 通过 project/specs/base.yml 中配置的preGenCommand自动运行本地化脚本 generate_strings.py，把 7-Zip 上百种语言的Lang/*.txt词表转成各语种的Upstream.strings；
3. 生成 Quick Action 扩展的InfoPlist.strings。

生成的工程默认不硬编码开发团队或签名身份，本地 Debug 构建在无团队时可用 ad-hoc 签名。如果只想验证编译、完全跳过签名，可以生成无签名变体：

SHICHIZIP_UNSIGNED=true xcodegen generate

它对应 project/specs/unsigned.yml 这份条件叠加配置（仅在SHICHIZIP_UNSIGNED存在时启用），会关闭 Debug/Release 的代码签名。验证完想恢复，不带该变量重新执行一次xcodegen generate即可。

💡 提示：每次修改了project/specs/下的规格或本地化源文件后，都需要重新运行xcodegen generate。

三、第二步：用 Zig 编译 7-Zip 静态库和 SFX 模块

ShichiZip 的压缩/解压能力来自上游 7-Zip 的 C/C++ 代码。构建脚本 build.zig 会先自动应用补丁（vendor/apply_7zip_patches.sh），再产出两类产物：

1）macOS 静态库（必须）

# Mainline 变体 zig build lib -Dvariant=mainline -Dtarget=aarch64-native -Doptimize=ReleaseFast -p build

Zstandard fork 变体改为-Dvariant=zs；Intel 机器把-Dtarget换成x86_64-native。产物输出到build/lib/（即lib7zip.a/lib7zip-zs.a），下一步 Xcode 会把它链接进 ArchiveCore framework。

2）Windows SFX 模块（自解压功能需要）

zig build sfx -Dvariant=mainline -Dsfx-arch=x86 -Doptimize=ReleaseSmall -p build

这些小模块在创建自解压压缩包时会被打包进 App。-Dsfx-arch也可以取x86_64或all，只是当前打包默认只带上x86版本。

💡 偷懒模式：zig build all可以一次跑完 lib + sfx 两个步骤，-Dvariant=all则同时构建两个上游代码树；代价是 SFX 产物会比上面分阶段命令更大一些。

四、第三步：用 Xcode 构建 macOS 应用

静态库就位后，用xcodebuild构建 App：

xcodebuild -project ShichiZip.xcodeproj -scheme ShichiZip -configuration Debug -arch arm64 build

Zstandard fork 换用-scheme ShichiZipZS；Intel 构建换-arch x86_64，发布构建换-configuration Release。

Xcode 这一步在背后做了关键的收尾工作（见 project/specs/archive-core.yml）：

• 通过-force_load把build/lib/里的静态库强制加载进ShichiZipArchiveCore.framework，让主 App 和 Quick Look 预览扩展共享同一份动态镜像；
• 把 framework 嵌入/签名到 App 的Contents/Frameworks，扩展通过 runpath 加载它；
• 嵌入 Quick Action 扩展和build/sfx/里对应的 SFX 模块。

顺手跑一下测试

每个变体都自带单测和 UI 测试 target，验证编译结果可以只跑单元测试：

xcodebuild -project ShichiZip.xcodeproj -scheme ShichiZip -configuration Debug -arch arm64 -only-testing:ShichiZipTests test

UI 测试会驱动真实 App 界面，运行时请不要碰键盘鼠标。完整测试矩阵（含ShichiZipZS变体）参考 BUILD.md。

五、构建流程串讲：三个工具如何接力

理解这条流水线后，遇到报错就知道去查哪一环：

1. Zig（build.zig）→ 给vendor/打上补丁，编译 7-Zip 静态库（含vendor/SZ*.mm的 Objective-C++ 垫片）与 Windows SFX 模块，输出到build/；
2. XcodeGen（project.yml）→ 生成ShichiZip.xcodeproj，并借 Python 脚本产出本地化文件；
3. Xcode→ 静态库 → ArchiveCore framework → 链接 App 与扩展，最终嵌入签名。

源码结构也围绕这套流程组织（见 BUILD.md）：ShichiZip/Bridge/是 Swift ↔ C++ 的桥接层，ShichiZip/QuickLookPreview/是 Quick Look 扩展，project/下则放着 XcodeGen 规格、构建脚本和本地化数据。

六、常见问题速查

小结

ShichiZip 的源码编译核心就是三步：xcodegen generate生成工程 →zig build产出 7-Zip 静态库和 SFX 模块 →xcodebuild构建 App。三个工具各司其职，命令都不长，照抄本文命令并留意 Zig 版本与子模块两个易错点，基本就能一次通过。祝你顺利构建出自己的 ShichiZip！