企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 机器学习
• 深度学习

导读

MediaPipeUnityPlugin 是一个面向 Unity（≥ 2022.3）的原生插件，目标是把 MediaPipe（基于 0.10.22 版本）的 C++ API逐一移植为 C# 接口，让开发者可以直接在 Unity 中编写 MediaPipe 代码、运行官方解决方案（Object Detection、Face Landmark、Hand Landmark、Pose Landmark 等），甚至运行自定义的Calculator与CalculatorGraph。本文以仓库根目录 README.md 为主体，结合 docs/ 下的教程与Runtime目录中的 C# 源码实现，系统梳理该插件的安装方式、支持平台与解决方案清单、Android 构建注意事项、示例场景运行方法，以及源码级的 API 底层原理，帮助你在自己的 Unity 项目中快速落地 MediaPipe 推理能力。

项目定位与设计目标

插件的核心设计思路可以概括为一句话：把 MediaPipe 的 C++ API 一对一地移植成 C# 可调用接口。这种"逐 API 包装"的思路在需要在循环中高频调用多个 API 的场景下可能会牺牲一部分性能，但它带来的是极高的灵活性——你可以在 C# 侧自由组合 MediaPipe 的各种能力，而不必被封装好的黑盒任务接口限制住。

具体来说，使用该插件你可以做到：

• 直接用 C# 编写 MediaPipe 代码；
• 在 Unity 中运行 MediaPipe 官方提供的解决方案；
• 在 Unity 中运行自定义的Calculator和CalculatorGraph（⚠️ 取决于输入/输出的类型，有时仍需编写少量 C++ 代码）。

从源码布局看，这一目标落实到 Packages/com.github.homuler.mediapipe/Runtime/Scripts/Framework/CalculatorGraph.cs 这类 C# 封装类上：它们通过UnsafeNativeMethods/SafeNativeMethods的 P/Invoke 调用原生库mediapipe_c（桌面端为libmediapipe_c.so/.dylib/.dll，Android 端为mediapipe_android.aar），上层再以托管对象（MpResourceHandle、Packet<T>等）管理原生资源生命周期。

第一个程序：C# 版 Hello World

README 给出了一个可直接运行的 Hello World 示例，它与 MediaPipe 官方 C++ 版hello_world.cc结构一一对应。核心代码位于Assets/MediaPipeUnity/Tutorial/Hello World/HelloWorld.cs（详见 docs/Tutorial-Hello-World.md）：

using Mediapipe; using UnityEngine; public sealed class HelloWorld : MonoBehaviour { private const string _ConfigText = @" input_stream: ""in"" output_stream: ""out"" node { calculator: ""PassThroughCalculator"" input_stream: ""in"" output_stream: ""out1"" } node { calculator: ""PassThroughCalculator"" input_stream: ""out1"" output_stream: ""out"" } "; private void Start() { using var graph = new CalculatorGraph(_ConfigText); using var poller = graph.AddOutputStreamPoller<string>("out"); graph.StartRun(); for (var i = 0; i < 10; i++) { graph.AddPacketToInputStream("in", Packet.CreateStringAt("Hello World!", i)); } graph.CloseInputStream("in"); var packet = new Packet<string>(); while (poller.Next(packet)) { Debug.Log(packet.Get()); } graph.WaitUntilDone(); } }

这个示例串起了 MediaPipe 数据流的最基本闭环，其中每个环节都有对应的源码实现可查：

• CalculatorGraph构造：CalculatorGraph(string textFormatConfig)内部先通过CalculatorGraphConfig.Parser.ParseFromTextFormat解析配置文本，再序列化为字节数组传给原生层（见 CalculatorGraph.cs）。若配置格式非法，构造器会直接抛异常。
• AddOutputStreamPoller<T>：在运行图之前，为输出流"out"注册一个OutputStreamPoller，泛型参数string即输出包中承载的数据类型（见 CalculatorGraph.cs）。
• StartRun()：启动图执行，出错时抛异常（如未设置CalculatorGraphConfig时）。
• AddPacketToInputStream：向输入流投递数据包。值得注意的是源码注释明确写着"respect move semantics"——packet.Dispose()会被调用，即包的所有权转移给图，调用方无需再手动释放（见 CalculatorGraph.cs）。
• CloseInputStream+WaitUntilDone：关闭输入流、等待图运行结束，是资源清理的标准流程。

更完整的逐步讲解（包括"时间戳缺失导致BadStatusException"、"如何通过OutputStreamPoller.Next接收输出"、"用Protobuf.SetLogHandler把解析日志打到 Console 窗口"等排错过程）都在 Tutorial-Hello-World.md 中，建议首次接触的读者先通读该教程。

安装方式

安装插件的首选途径是从 releases 页面下载预编译包，而不是自己编译。release 提供四种产物，各有适用场景：

需要特别强调的是：如果要在移动设备上运行示例场景，优先选择MediaPipeUnityPlugin-all.zip或-all-stripped.zip。因为运行示例需要把模型（.tflite）正确放置到资源目录，而all系列包已经完成了绝大部分的配置工作，导入即可运行。.unitypackage与.tgz适合在桌面端或自有项目中按需接入。

下载后通过 Unity 的标准方式导入即可：.unitypackage用 Import 流程导入，.tgz则作为 UPM tarball 包引入。

支持平台

插件支持的平台矩阵（注意：macOS 与 Windows 不支持 GPU 模式）：

从该表可以读出两层信息：其一，Editor 是所有桌面系统共有的开发环境，开发调试可以直接在 UnityEditor 内进行；其二，Android 是覆盖面最广的目标平台，四类宿主系统都能构建 Android 版本，而 iOS 仅能从 macOS 宿主构建。WebGL 目前不在支持之列。

支持的解决方案

插件实现了以下 MediaPipe Tasks（任务 API）的 C# 接口，支持情况如下：

可见五大计算机视觉任务（目标检测、图像分割、手势/人手、人脸检测与人脸关键点、姿态关键点）以及音频分类是当前完整支持的领域，其余任务（LLM、图像生成、文本类任务等）尚未接入。

此外，插件还支持通过MediaPipe Framework运行Legacy 解决方案（如 Face Mesh、Holistic），但需要注意官方对这些旧方案已停止维护，仅作兼容性保留。Legacy 方案的使用方式详见 Tutorial-Custom-Graph.md。

使用指南

Android 构建注意事项：务必带上libstdc++_shared.so

⚠️ 如果你要为 Android 构建应用，必须确保 APK 中包含libstdc++_shared.so，否则运行时将抛出DllNotFoundException。

原因在 README 的脚注中有明确说明：mediapipe_android.aar内含libopencv_java4.so，而它依赖libstdc++_shared.so；但由于部分项目/插件可能已经自带该库，所以官方没有把它打进mediapipe_android.aar。

最简单的做法是把libstdc++_shared.so放到项目的Assets/Plugins/Android目录下。也可以在构建时通过修改 Unity 的mainTemplate.gradle（本仓库的模板见 Assets/Plugins/Android/mainTemplate.gradle）自动拷贝，示例项目采用的就是这一方案。根据 NDK 版本不同，模板代码分为两种：

NDK ≥ 23时，通过任务把 NDK 预编译目录中的libc++_shared.so按 ABI 映射复制到src/main/jniLibs：

// Include libc++_shared.so task copyLibcppShared { doLast { def ndkDir = android.ndkDirectory def abiFilters = android.defaultConfig.ndk.abiFilters def destDir = file("$projectDir/src/main/jniLibs") // Mapping from ABI to architecture triple (for NDK 23+) def abiToTriple = [ 'arm64-v8a': 'aarch64-linux-android', 'armeabi-v7a': 'arm-linux-androideabi', 'x86': 'i686-linux-android', 'x86_64': 'x86_64-linux-android', 'riscv64': 'riscv64-linux-android' ] // Find the prebuilt directory (usually there's only one) def prebuiltDir = null def prebuiltBase = file("$ndkDir/toolchains/llvm/prebuilt") if (prebuiltBase.exists()) { def prebuiltDirs = prebuiltBase.listFiles()?.findAll { it.isDirectory() } if (prebuiltDirs && prebuiltDirs.size() > 0) { prebuiltDir = prebuiltDirs[0] } } abiFilters.each { abi -> if (prebuiltDir != null) { def triple = abiToTriple[abi] if (triple != null) { def libcppPath = file("$prebuiltDir/sysroot/usr/lib/$triple/libc++_shared.so") if (libcppPath.exists()) { def destAbiDir = file("$destDir/$abi") copy { from libcppPath into destAbiDir } } } } } } } task cleanCopyLibcppShared { doLast { def destDir = file("$projectDir/src/main/jniLibs") def abiFilters = android.defaultConfig.ndk.abiFilters abiFilters.each { abi -> def libcppFile = file("$destDir/$abi/libc++_shared.so") if (libcppFile.exists()) { libcppFile.delete() } } } } clean.dependsOn 'cleanCopyLibcppShared' tasks.whenTaskAdded { task -> if (task.name == "mergeDebugJniLibFolders" || task.name == "mergeReleaseJniLibFolders") { task.dependsOn("copyLibcppShared") } }

NDK < 23时，直接从旧版 NDK 的sources/cxx-stl/llvm-libc++/libs目录复制：

// Include libc++_shared.so task copyLibcppShared(type: Copy) { def ndkDir = android.ndkDirectory from("$ndkDir/sources/cxx-stl/llvm-libc++/libs") { include '**/libc++_shared.so' } into("$projectDir/src/main/jniLibs") } clean.dependsOn 'cleanCopyLibcppShared' tasks.whenTaskAdded { task -> if (task.name == "mergeDebugJniLibFolders" || task.name == "mergeReleaseJniLibFolders") { task.dependsOn("copyLibcppShared") } }

两个片段的核心逻辑一致：把clean与merge*JniLibFolders任务挂钩，保证每次构建前把共享库同步进jniLibs。

运行示例场景

在正式接入自己的项目前，强烈建议先确认示例场景能正常运行。示例场景位于 Assets/MediaPipeUnity/Samples/Scenes 目录下，覆盖以下方案：

• Face Detection
• Face Landmark Detection
• Hand Landmark Detection
• Image Segmentation
• Object Detection
• Pose Landmark Detection
• Legacy（Holistic、MediaPipe Video 等旧方案）

UnityEditor 环境

直接在 Assets/MediaPipeUnity/Samples/Scenes 下任选一个场景并播放即可，Editor 内置了资源加载所需的配置。

Desktop / Android / iOS 环境

在设备上运行时，需要在 Inspector 窗口中配置两个关键选项：Inference Mode与Asset Loader Type。

Inference Mode（推理模式）：如果原生库是按 CPU 构建的（即--desktop cpu），请选择CPU。release 页面分发的桌面库（Windows/macOS）目前只提供 CPU 版本，因此这两个平台上请保持CPU。

Asset Loader Type（资源加载器）：默认值是Local，它只在 UnityEditor 下有效。要在真机（Android/iOS 或桌面独立构建）上运行，需要切换为StreamingAssets，并把所需资源复制到StreamingAssets目录下（如果使用MediaPipeUnityPlugin-all.zip，该目录已经包含所需资源）。

从源码看，这两个配置项分别对应了 Runner 脚本中的执行路径与资源管理器选择：

• 推理模式的选择对应 InferenceMode.cs 与 RunningMode.cs 等枚举；TaskApiRunner/VisionTaskApiRunner会根据配置决定是否走 GPU 资源路径。
• 资源加载器对应IResourceManager接口的三个实现（详见下文"资源管理器"小节），StreamingAssets即StreamingAssetsResourceManager，其从Application.streamingAssetsPath加载模型并保存到本地可读路径。

自行构建插件

README 明确提醒：大多数情况下你不需要自行构建插件，只有当预编译包无法满足需求时才需要。但要注意：本仓库不包含所需的原生库（.so/.dll/.aar等）和模型（.tflite等），如果你直接 clone 本仓库，就必须自行构建。完整的构建指南见 docs/Build.md，这里摘录其要点。

哪些情况需要自行构建

• 想通过移除冗余代码来缩小库体积；
• 想使用 release 包中未包含的 Calculator；
• 想尝试尚未进入 release 的最新特性；
• 想使用不同版本（尤其是自定义版本）的 MediaPipe。

推荐方式：GitHub Actions

仓库带有构建库的 GitHub Actions Workflow，这是最简单的方式：fork 本仓库后，在 fork 中运行 build-package workflow 即可。需要填写的参数与下文"Build 命令"一致。

本地构建

本地构建主要服务于在 PC 上做试错迭代。各平台的前置依赖在 docs/Build.md 中有详细清单，核心要求包括：

• Python（≥ 3.9.0 且 < 3.13.0）；
• Bazelisk（最新版）；
• GCC/G++ ≥ 13.0.0、Clang ≥ 16.0.0、binutils ≥ 2.40（Linux）；
• NuGet（最新版）；
• macOS 还需 Xcode ≥ 16.0 及 Command Line Tools；Windows 还需 MSYS2、Visual C++ Build Tools 2022 + WinSDK。

Linux 下强烈推荐使用仓库提供的 Docker 镜像构建（Dockerfile 见 docker/linux/x86_64/Dockerfile）：

docker build --build-arg UID=$(id -u) -t mediapipe_unity:latest . -f docker/linux/x86_64/Dockerfile docker run \ --mount type=bind,src=$PWD/Packages,dst=/home/mediapipe/Packages \ --mount type=bind,src=$PWD/Assets,dst=/home/mediapipe/Assets \ -it mediapipe_unity:latest

Windows 侧同样提供 Windows 容器（要求 Hyper-V 后端，Windows 10/11 Home 不支持）与 Linux 容器（仅能构建 Android 库）两种方式，Dockerfile 见 docker/windows/x86_64/Dockerfile。

Build 命令

构建脚本支持三个子命令：

常用构建命令示例（完整参数可用python build.py build --help查看）：

# 桌面端构建，启用 GPU python build.py build --desktop gpu --opencv cmake -vv # 桌面端构建，禁用 GPU python build.py build --desktop cpu --opencv cmake -vv # 构建通用 macOS 库（仅 macOS） python build.py build --desktop cpu --opencv cmake --macos_universal -vv # 同时构建桌面端、Android 与 iOS python build.py build --desktop cpu --android arm64 --ios arm64 --opencv cmake -vv # 指定 Android NDK 级别 python build.py build --android arm64 --android_ndk_api_level 21 -vv # 只构建指定解决方案所需的库 python build.py build --desktop gpu --opencv cmake --solutions face_mesh hands pose -vv

还可以控制编译模式与链接选项：

# 带调试符号构建 python build.py build -c dbg --android arm64 -vv # 剥离全部符号信息（可显著减小库体积） python build.py build --android arm64 --linkopt=-s -vv

两个值得注意的坑：

1. GLibc 兼容性：在 Linux 上构建的libmediapipe_c.so，目标机器的 GLibc 版本不能低于构建机的版本（Docker 构建要求目标机 GLibc ≥ 2.31），否则库无法加载。
2. Windows 换行符：Windows 下构建绝不能设置core.autocrlf（可用git config -l检查），源码必须以原始换行符检出，否则会出现$'\r': command not found或PKGBUILD contains CRLF characters之类的错误。

常见故障：DllNotFoundException

构建/运行中最常见的错误是DllNotFoundException，docs/Build.md 给出了系统的排查顺序：

1. 原生库尚未构建：确认Packages/com.github.homuler.mediapipe/Runtime/Plugins下存在对应平台的库文件，先跑一次 build 命令；
2. 库与设备不兼容：Linux 构建的库不能用于 Windows；Android 侧则检查架构参数（如--android armv7）、API Level（用--android_ndk_api_level指定）以及 APK 是否包含libc++_shared.so；
3. 依赖库未链接：典型场景是 OpenCV 配置不当导致符号未定义（如undefined symbol: _ZN2cv8fastFreeEPv），可用--opencv cmake改为静态链接 OpenCV；
4. 依赖库缺失或未加载：动态链接 OpenCV 时目标机器也必须安装 OpenCV，可用ldd等工具检查依赖；
5. 仍无法定位原因：在 Unity 插件检查器中勾选"Load on startup"，或编写代码在运行时手动加载库以获取更详细的错误信息（README 的 Build 文档中提供了 Android 的AndroidJavaClass("java.lang.System").CallStatic("loadLibrary", "mediapipe_jni")、Windows 的LoadLibraryW、Linux/macOS 的dlopen三套排查代码）。

自行打包

拿到MediaPipeUnityPlugin-all(-stripped).zip后，也可以自己产出可分发的包。

构建 unitypackage：打开项目后点击Tools > Export Unitypackage，会在项目根目录生成MediaPipeUnity.[version].unitypackage。对应实现见 Assets/MediaPipeUnity/Editor/PackageExporter.cs。

构建本地 tarball：需要先安装npm命令，然后在Packages/com.github.homuler.mediapipe目录（其 package.json 定义了包名与版本）下执行：

cd Packages/com.github.homuler.mediapipe npm pack # com.github.homuler.mediapipe-[version].tgz 将在此目录生成 mv com.github.homuler.mediapipe-[version].tgz your/favorite/path

技术限制：崩溃风险与 Graphics API

UnityEditor / 应用可能崩溃

插件底层是原生库，一旦原生库存在 bug，就可能拖垮 UnityEditor 或应用进程。更棘手的是，某些情况下 MediaPipe 会通过发送SIGABRT信号而不是抛出异常来终止整个程序——这在生产环境通常不成问题（多半是应用代码的致命 bug，发布前应已修复），但开发期会让 UnityEditor 直接崩溃，非常恼人。

• Linux 与 macOS：插件已通过处理SIGABRT避免 UnityEditor 崩溃；
• Windows：目前没有妥善处理SIGABRT的方式，如果无法忍受，请换用其他操作系统。

Graphics API 限制

如果要用 GPU 跑推理，不能使用 OpenGL Core API，否则会遇到类似下面的错误：

InternalException: INTERNAL: ; eglMakeCurrent() returned error 0x3000_mediapipe/mediapipe/gpu/gl_context_egl.cc:261)

实际上该错误基本只出现在 PC 独立构建中，此时请把 Graphics API 切换到Vulkan。

从源码看关键 API 的底层实现

为了让读者对插件机制有更扎实的理解，这里结合 Packages/com.github.homuler.mediapipe/Runtime/Scripts 的源码补充几个关键组件的工作原理。

CalculatorGraph：托管壳与原生资源的桥接

CalculatorGraph.cs 继承自MpResourceHandle，其生命周期与原生mp_CalculatorGraph*指针绑定。值得关注的方法包括：

• AddPacketToInputStream<T>：投递包并立即 Dispose 该包（注释明确为 "respect move semantics"，即移动语义），调用方无需管理包内存；
• AddOutputStreamPoller<T>：返回OutputStreamPoller<T>，底层对应原生mp_CalculatorGraph__AddOutputStreamPoller__PKc_b；
• SetGpuResources/GetGpuResources：管理 GPU 资源，配合 GPU 模式的图运行；
• ObserveOutputStream<T>：注册原生回调（NativePacketCallback），供OutputStream的事件监听使用，回调通过GCHandle.Alloc(..., GCHandleType.Pinned)固定以防止 GC 回收。

OutputStream：异步取结果的便捷 API

在 Legacy 方案（自定义图）中，官方教程更推荐使用 OutputStream.cs 而非手动轮询：OutputStream<T>内部持有OutputStreamPoller<T>，通过WaitNextAsync()返回Task<NextResult>（包含packet与ok），并支持AddListener事件回调。其实现要点包括：

• observeTimestampBounds参数控制"无输出时的行为"：为true时流会输出空包（此时WaitNextAsync返回packet == null的NextResult），为false时则不产生任何输出（源码注释见 OutputStream.cs）；
• AddListener还提供emptyPacketThresholdMicrosecond参数，用于忽略"空包风暴"——即距上次非空输出未超过指定微秒数的空包不会触发回调（见 OutputStream.cs）。

IResourceManager：模型资源的统一入口

MediaPipe 的图在运行时会按硬编码路径读取.tflite等模型文件，因此插件提供了IResourceManager接口（见 ResourceManager.cs），核心方法是PrepareAssetAsync(name, uniqueKey, overwriteDestination)，它会异步地把资源保存到本地可读路径，并在内部通过ResourceUtil.AddAssetPath/SetAssetPath注册资源路径，让原生层能读到。三种实现对应不同场景：

• LocalResourceManager.cs：测试用；
• StreamingAssetsResourceManager.cs：从Application.streamingAssetsPath加载，开发/生产常用；
• AssetBundleResourceManager.cs：从 AssetBundle 加载。

Legacy 方案中的模型文件使用.bytes扩展名（Unity 不支持.tflite的TextAsset导入，.bytes与.tflite内容完全相同），典型用法是：

IResourceManager resourceManager = new LocalResourceManager(); yield return resourceManager.PrepareAssetAsync("face_detection_short_range.bytes"); yield return resourceManager.PrepareAssetAsync("face_landmark_with_attention.bytes");

GpuManager：GPU 资源初始化助手

GPU 模式（如face_mesh_desktop_live_gpu.pbtxt或 Task API 的 GPU Delegate）下，需要先初始化 GPU 资源再运行图。GpuManager.cs 是一个静态助手：GpuManager.Initialize()会检测 Graphics API，若为 OpenGLES3 则通过AsyncGlContext.Request异步获取 Unity 的 EGL 上下文，再创建GpuResources与GlCalculatorHelper；Shutdown()必须在应用退出前调用，否则 UnityEditor 可能冻结。典型流程：

yield return GpuManager.Initialize(); if (!GpuManager.IsInitialized) { throw new System.Exception("Failed to initialize GPU resources"); } graph = new CalculatorGraph(configAsset.text); graph.SetGpuResources(GpuManager.GpuResources);

注意：若在 Task API 的CreateFromOptions中传入GpuResources以共享 OpenGL Context（避免 CPU 侧拷贝输入图像，Android/OpenGL ES 下尤其有用），需要先通过GpuManager.Initialize()初始化，且Graphics API 为 OpenGL Core 时会失败。详见 docs/Tutorial-Task-API.md。

TextureFrame：坐标翻转的便捷工具

MediaPipe 与 Unity 的像素坐标系原点不同（Unity 以左下角为原点，MediaPipe 使用左上角为原点的 Image Coordinate System），直接传数据会导致图像垂直翻转。实验性的 TextureFrame.cs 封装了ReadTextureOnCPU(webCamTexture, flipHorizontally, flipVertically)与BuildImageFrame()/BuildCPUImage()，一句话完成"读帧 + 翻转 + 构建输入"：

using var textureFrame = new Experimental.TextureFrame(webCamTexture.width, webCamTexture.height, TextureFormat.RGBA32); textureFrame.ReadTextureOnCPU(webCamTexture, flipHorizontally: false, flipVertically: true); using var imageFrame = textureFrame.BuildImageFrame(); graph.AddPacketToInputStream("input_video", Packet.CreateImageFrameAt(imageFrame, (long)currentTimestamp));

许可证说明

插件主体以 MIT 协议 分发，但仓库内部分文件遵循其他许可证：

• MediaPipe：Apache License 2.0；
• emscripten：MIT（third_party/mediapipe_emscripten_patch.diff包含来自 emscripten 的代码）；
• FontAwesome：其自有许可证（示例场景使用了 Font Awesome 字体）。

更完整的第三方声明见仓库根目录的 Third Party Notices.md。

继续深入

本文只覆盖了插件的安装、平台与使用主线。若要进一步落地到具体方案，建议按以下顺序研读 docs/ 目录：

• docs/README.md：文档目录总览；
• docs/Tutorial-Hello-World.md：理解CalculatorGraph/Packet/OutputStreamPoller基础概念；
• docs/Tutorial-Task-API.md：使用官方 Task API（FaceLandmarker 为例），涵盖 Delegate、RunningMode、模型路径、旋转图像处理与零分配优化；
• docs/Tutorial-Custom-Graph.md：运行自定义CalculatorGraph（Face Mesh Legacy 为例），涵盖资源准备、时间戳微秒单位与 GPU 支持；
• docs/Build.md：完整的本地构建与故障排查手册；
• docs/Logging.md：日志输出配置。

同时，示例场景与 Runner 脚本位于 Assets/MediaPipeUnity/Samples/Scenes 与 Assets/MediaPipeUnity/Samples/Common/Scripts，是阅读真实工程用法的最佳起点。

• 人工智能
• 计算机视觉
• 机器学习
• 深度学习