# macOS 安装 Unitree SDK2 Python 卡在 cyclonedds

> 原文链接：https://robotics.hellobike.com/pitfalls/unitree-sdk2-python-macos-cyclonedds
> 频道：pitfalls | 更新日期：2026-10-10 | 标签：macOS, cyclonedds, 环境配置
> 核心摘要：解释 macOS 安装失败的原因，以及开发机和机器人局域网 Ubuntu 机器之间的正确分工。

# macOS 安装 Unitree SDK2 Python 卡在 cyclonedds

## 问题现象与根因

# macOS 安装失败不是待修复的项目缺陷

在 macOS 上直接执行 `pip install unitree_sdk2py`，安装过程会停在 cyclonedds 依赖：当前依赖链没有可用的 macOS wheel，因此本地环境无法按这条路径完成安装。反复切换 Python 小版本、修改业务代码或强行拼装依赖，不能改变运行平台不受支持这一事实，反而容易制造一套无法复现的个人环境。

正确做法是按机器职责拆分。macOS 开发机只承担内容、云端逻辑、接口开发和模拟运行，不发起面向真实机器人的 SDK 通信。需要执行真机脚本时，改用已经接入机器人局域网的 Ubuntu 机器，在该机器上建立独立 Python 环境并安装、验证 SDK。这样既符合网络接入条件，也避免把真机依赖扩散到日常开发环境。

排查时先确认失败包确实是 cyclonedds，再检查当前系统是不是 macOS。若两项同时成立，应把结果记录为预期的不兼容环境，并转到 Ubuntu 真机工作站继续，而不是把“在 macOS 上装成功”当作交付目标。SDK 版本、机器人型号和网络条件仍需在实际运行记录中单独注明。

## 排查与解决步骤

1. **核对架构与依赖版本**：确认 macOS (`arm64` / Apple Silicon) 下 Python 虚拟环境与 `cyclonedds` C 动态库架构一致，设置 `CYCLONEDDS_HOME` 指向编译安装目录。
2. **绑定物理网卡接口**：在 CycloneDDS XML 配置中将 `<NetworkInterfaceAddress>` 显式指定为连接到机器人的有线以太网接口（如 `en0` 或 `en5`），避免默认绑定到回环或 Wi-Fi 接口导致组播丢包。
3. **验证 DDS 话题连通性**：运行示例前先通过高层状态订阅脚本验证 `rt/sportmodestate` 话题周期是否稳定在 50Hz~500Hz。

## 原始参考来源 (Sources)

- [unitree_sdk2_python](https://github.com/unitreerobotics/unitree_sdk2_python)