如何在 macOS 上构建 OBS Background Removal 插件：Xcode、vcpkg 与 CMake 开发环境搭建实战指南

• 人工智能
• 计算机视觉
• 视频处理

本篇指南完整讲解如何在 macOS 上从源码搭建 OBS Background Removal（OBS 人像背景移除 / 虚拟绿幕与低光增强插件）的开发环境，覆盖 Xcode 16.4 安装、Homebrew/CMake 系统依赖、vcpkg 依赖管理、ONNX Runtime 下载、CMake 预设配置与构建、本地插件安装调试以及 clang-format/gersemi 代码规范检查的全部步骤。读完本文，你将能够在本机完成该插件的全流程编译、将产物装入系统 OBS 实测，并掌握与仓库内 CMake 预设、vcpkg 三元组和打包脚本相互印证的底层构建原理。

一、构建全景：技术栈与 macOS 平台要点

OBS Background Removal 是一个基于神经网络的人像分割 OBS 插件，通过 ONNX Runtime 推理预训练模型生成前景掩膜，从而在直播或录屏时轻松替换背景，并附带低光增强能力。其核心源码位于 src，而 macOS 上的构建主要涉及以下技术栈（可对照 CMakeLists.txt 确认）：

• 语言标准：C++20 / C17，由 CMakeLists.txt 强制设定；
• 构建系统：CMake，最低版本 3.28（见 CMakeLists.txt）；
• 推理引擎：ONNX Runtime（含 CUDA/ROCm 执行提供程序的编译期检测，见 CMakeLists.txt）；
• 图像处理：OpenCV 4（opencv_core / opencv_imgproc / opencv_geometry）；
• OBS 接口：libobs、obs-frontend-api 以及 Qt6 Widgets；
• 网络组件：CURL（用于更新检查，见 src/update-checker）。

macOS 平台有两个必须提前知道的特殊点：

1. 架构必须原生匹配：该插件不支持 Rosetta2 跨架构转译。在 Apple Silicon 上运行 Intel 版 OBS/插件、或在 Intel Mac 上运行 Apple Silicon 版二进制都会崩溃，请始终使用与本机架构一致的 OBS Studio 与插件构建（pages/src/pages/macos.astro 中亦有明确警告）。
2. 官方构建以 Apple Silicon（arm64）为准：仓库内的 macOS 依赖三元组与 CMake 预设均面向 arm64，例如 vcpkg-triplets/arm64-osx-obs-ort.cmake 将VCPKG_TARGET_ARCHITECTURE固定为 arm64；Intel x64 对应三元组（vcpkg-triplets/x64-osx-obs-ort.cmake）同样存在，但本仓库 CMakePresets.json 内置的 macOS 预设仅针对 arm64。

二、第 1 步：安装 Xcode 16.4

官方开发指南明确要求使用Xcode 16.4，且App Store 版本不可用，必须从 Apple Developer Downloads 页面单独下载（需要 Apple ID 登录，无需开发者计划付费会员）。安装完成后，在终端中导出开发者目录，使命令行工具链指向该版本的 Xcode：

export DEVELOPER_DIR=/Applications/Xcode_16.4.0.app

DEVELOPER_DIR是 Apple 工具链的标准环境变量，CMake、xcrun、编译器定位等都会读取它。将其指向非 App Store 的 Xcode 包，可以避免系统默认工具链版本与 CI 构建环境不一致导致的编译问题。建议把该 export 写入 shell 配置文件（如~/.zshrc），以便每次打开终端都能保持正确的工具链环境。

三、第 2 步：安装系统依赖（Homebrew + CMake）

若本机尚未安装 Homebrew，请先安装 Homebrew（macOS 上最常用的软件包管理器）。随后安装 CMake：

brew install cmake

结合 CMakeLists.txt 可知，本项目要求cmake_minimum_required(VERSION 3.28)，因此请确保brew install得到的 CMake 版本不低于 3.28。若 Homebrew 默认源中的版本过旧，可通过brew upgrade cmake更新。

四、第 3 步：获取源码

将项目源码克隆到本地工作目录并进入项目根目录。本仓库为该项目的一份镜像，可直接克隆本仓库地址进行开发：

git clone https://gitcode.com/gh_mirrors/ob/obs-backgroundremoval.git cd obs-backgroundremoval

进入目录后可以快速验证关键构建文件是否齐备，例如根目录下的 CMakeLists.txt、CMakePresets.json、vcpkg.json 与 vcpkg-configuration.json。注意：官方文档中引用的部分开发辅助脚本（如.github/scripts/、cmake/、build-aux/目录）属于上游 CI 与工具链仓库的组成部分，本镜像仓库中不包含这些文件，后续步骤中遇到这些路径时请以其命令语义为准。

五、第 4 步：搭建 vcpkg

vcpkg 是本项目管理第三方依赖（OpenCV、curl、cpuinfo 等）的核心工具。克隆并引导 vcpkg，然后导出VCPKG_ROOT：

git clone https://github.com/microsoft/vcpkg.git ~/vcpkg ~/vcpkg/bootstrap-vcpkg.sh export VCPKG_ROOT=~/vcpkg

从仓库配置文件可以进一步理解 vcpkg 在本项目中的角色：

• vcpkg-configuration.json 通过overlay-triplets指向仓库内 vcpkg-triplets 目录，并注册了kaito-tokyo/vcpkg-registry-kaito-tokyo私有注册表用于提供wolfssl包（macOS 上 curl 的 SSL 后端）；
• vcpkg.json 声明了插件依赖：cpuinfo、按平台区分的curl（Windows/macOS 差异配置）以及启用jpeg特性的opencv4；
• 以 vcpkg-triplets/arm64-osx-obs-ort.cmake 为代表的 macOS 三元组设定了VCPKG_CMAKE_SYSTEM_NAME=Darwin、VCPKG_TARGET_ARCHITECTURE=arm64、静态库链接、C++20 标准以及VCPKG_OSX_DEPLOYMENT_TARGET="13.0"等参数。

六、第 5 步：安装构建依赖（耗时约 10–20 分钟）

运行仓库提供的 macOS 依赖安装脚本，该步骤会拉取并编译 OBS 依赖（obs-deps、obs-frontend-api、Qt6 等），官方文档提示可能需要10–20 分钟：

./.github/scripts/install-vcpkg-macos.bash

该脚本位于上游仓库的.github/scripts目录（本镜像未包含此目录）。从 CMakePresets.json 可以看出，依赖安装的最终落点是CMAKE_PREFIX_PATH中的.deps/obs-deps、.deps/obs-deps-qt6、obs_installed、vcpkg_ort_installed/arm64-osx-obs-ort、ort_installed与vcpkg_installed/arm64-osx-obs等目录——即依赖安装脚本的产物将在此后的 CMake 配置阶段被自动搜索。这一步骤较耗时属正常现象，请耐心等待其完成，不要中断。

七、第 6 步：下载 ONNX Runtime

通过 CMake 脚本模式下载并准备 ONNX Runtime：

cmake -P cmake/DownloadOnnxruntime.cmake

该脚本同样位于上游cmake/目录（本镜像未包含）。ONNX Runtime 在构建中的定位可以从 CMakeLists.txt 验证：构建系统先通过find_package(onnxruntime CONFIG)查找，失败时回退到 pkg-config；随后通过check_cxx_symbol_exists检测OrtSessionOptionsAppendExecutionProvider_CUDA/_ROCM符号以决定是否启用对应执行提供程序。需要说明的是，macOS 场景下插件使用的是 CoreML 加速（对 Apple Silicon 高效），而 CUDA/ROCm 检测主要服务于 Linux 自编译场景；在 macOS 上请确保所下载的 ONNX Runtime 与 arm64 架构匹配。

八、第 7 步：配置并构建项目

使用 CI 预设完成配置：

cmake --preset macos-ci

使用 CI 预设完成构建：

cmake --build --preset macos-ci

这里有一个需要注意的预设名差异：官方文档给出的预设名为macos-ci，它由上游 CI 工作流定义；而当前镜像仓库 CMakePresets.json 中内置的 macOS 预设名为macos-arm64，其核心设置包括：

• binaryDir为build，构建类型为RelWithDebInfo；
• CMAKE_OSX_ARCHITECTURES=arm64，CMAKE_OSX_DEPLOYMENT_TARGET=13.0；
• CMAKE_PREFIX_PATH覆盖上文提到的 obs-deps、obs_installed、vcpkg_ort_installed、vcpkg_installed 等依赖目录。

因此，若你在本镜像上开发，可以按需将命令替换为cmake --preset macos-arm64与cmake --build --preset macos-arm64，效果等价于文档所述的 CI 构建。构建过程还有两点源码层面的佐证：

• 编译器选项在 UNIX 分支启用了-Wall -Wextra -Werror以及-fopenmp-simd（见 CMakeLists.txt），即构建时把警告当作错误，代码需保持零警告；
• macOS 分支下插件目标被设置为BUNDLE TRUE且扩展名为.plugin，并链接 src/exported_symbols_macos.txt 指定的符号导出白名单（见 CMakeLists.txt 与 CMakeLists.txt）；
• 若开启了BUILD_TESTING，配置阶段还会通过add_subdirectory(tests)引入 tests/CMakeLists.txt 中的测试，构建完成后可用ctest运行验证。

九、第 8 步：在系统 OBS 中测试插件

构建完成后，将插件 bundle 复制到系统 OBS 的插件目录：

cp -r build_macos/RelWithDebInfo/obs-backgroundremoval.plugin ~/Library/Application\ Support/obs-studio/plugins

关于目标路径与产物结构，仓库源码给出了明确印证：在 CMakeLists.txt 的 APPLE 分支中，插件被配置为.plugin扩展名的 bundle，安装目标为Library/Application Support/obs-studio/plugins（即用户目录~/Library/...下）；同时，特效文件（data/effects下的 blend_images、kawase_blur、mask_alpha_filter）、多语言本地化文件（data/locale下的 14 种语言 ini）以及全部 ONNX 模型（data/models）都会被打包进 bundle 的Resources/effects、Resources/locale、Resources/models子目录。

两点实操提醒：

1. 产物路径以预设为准：文档命令中的build_macos目录来自 CI 构建命名；本仓库 CMakePresets.json 的binaryDir为build，若使用macos-arm64预设，对应产物路径应为build/RelWithDebInfo/obs-backgroundremoval.plugin，请按实际构建输出目录调整；
2. 重启 OBS 并保持架构一致：复制完成后重启 OBS Studio（若正在运行），并在“源/滤镜”中验证插件是否加载；务必确保 OBS 与插件均为同一原生架构（Apple Silicon 用 arm64），避免 Rosetta2 转译导致的崩溃。

十、第 9 步：代码风格检查（clang-format / gersemi）

提交代码前，请安装官方推荐的格式化工具并运行 lint 脚本：

brew install obsproject/tools/clang-format@19 obsproject/tools/gersemi ./build-aux/run-clang-format ./build-aux/run-gersemi

• clang-format@19来自obsproject/toolsHomebrew tap，用于统一 C/C++ 代码风格（对应仓库 src 下的 C/C++ 源文件）；
• gersemi是 CMake 文件专用格式化工具，用于规范 CMakeLists.txt 与 CMakePresets.json 等构建脚本的排版；
• build-aux/run-clang-format与build-aux/run-gersemi为上游仓库的辅助脚本（本镜像未包含build-aux目录），若在镜像上开发，可参照其语义直接调用对应工具二进制完成检查。

十一、常见问题速查

十二、延伸阅读

• 其他平台的开发指南：pages/src/pages/dev/ubuntu.md、pages/src/pages/dev/windows.md、pages/src/pages/dev/index.astro；
• 插件安装与使用说明：pages/src/pages/macos.astro、pages/src/pages/usage.astro；
• 构建配置与依赖声明：CMakePresets.json、CMakeLists.txt、vcpkg.json、vcpkg-configuration.json；
• macOS 导出符号清单：src/exported_symbols_macos.txt。

至此，你的 macOS 本地开发环境已搭建完成，可以开始编译、调试并为本插件贡献代码了。

• 人工智能
• 计算机视觉
• 视频处理