macOS 上使用 PyCharm 远程开发 Isaac ROS

本文档的目标是在 macOS 上使用 PyCharm 编写和调试 Isaac ROS 代码，在远程 Ubuntu GPU 主机上运行 Isaac ROS、Docker、ROS 2、CUDA 和传感器驱动

为什么这么做：

工作边界：

• macOS：PyCharm UI、SSH、Git、调试入口。
• 远程主机：Isaac ROS workspace、Docker、ROS 2、CUDA、TensorRT、传感器和机器人硬件接口。
• Isaac ROS 容器：ros2、colcon、Python 节点、launch 文件的实际运行环境。

本文不讲解 Isaac ROS 官方安装细节。Isaac ROS 安装以官方文档为准；本文补齐 macOS + PyCharm 远程开发链路。环境隔离使用 Docker。除非需要调试驱动、设备权限或系统依赖，否则不要把 Isaac ROS 的 Python、TensorRT、OpenCV 等依赖铺到远程宿主机系统环境里

1. 推荐架构

开发结构：

操作规则：PyCharm 连接远程主机；运行 Isaac ROS 节点前，在 PyCharm Terminal 中执行 isaac-ros activate 进入容器。

2. 在远程主机安装 Isaac ROS

执行顺序：先让 Isaac ROS 在远程 Ubuntu GPU 主机上独立跑通，再配置 macOS 和 PyCharm。

2.1 确认远程主机可用

远程主机使用 x86_64 Ubuntu 24.04 + NVIDIA GPU，ROS 发行版使用 Jazzy。先从 macOS 登录远程主机：

ssh user@remote-host

验证 SSH 成功后，再确认 NVIDIA GPU 驱动可见：

nvidia-smi
lsb_release -a

确认结果：macOS 能稳定 SSH 登录远程主机，nvidia-smi 能看到 NVIDIA GPU 和驱动信息，lsb_release -a 显示 Ubuntu 24.04。

2.2 按官方文档安装 Isaac ROS

参考一下两个官方文档安装环境，了解 workspace 挂载和 isaac-ros activate 工作流

• NVIDIA Isaac ROS Getting Started
• Isaac ROS Development Environment

在远程主机上按官方文档完成：

1. 安装或确认 NVIDIA 驱动。
2. 安装 Docker 和 NVIDIA Container Toolkit。
3. 配置 Isaac ROS APT 仓库。
4. 安装 isaac-ros-cli。
5. 创建 Isaac ROS workspace，例如 ~/workspaces/isaac_ros-dev。
6. 执行 isaac-ros init docker 初始化 Docker 开发环境。

安装完成后，在远程主机上验证 CLI 和 workspace：

echo $ISAAC_ROS_WS
isaac-ros --help
test -d "${ISAAC_ROS_WS}/src" && echo "workspace ok"

看到 workspace 路径、isaac-ros 帮助信息和 workspace ok 后，再进入下一步。

2.3 进入 Docker 开发环境并验证 ROS 2

进入 Isaac ROS Docker 开发环境：

cd $ISAAC_ROS_WS
isaac-ros activate

进入容器后验证 ROS 2 基础命令：

ros2 --help
ros2 pkg list

ros2 --help 能输出帮助信息，说明 ROS 2 命令可用；ros2 pkg list 能列出当前环境可发现的 package，说明当前 shell 已经具备 ROS 2 package 发现能力。

如果这一步失败，不要继续。先回到 Getting Started 文档修远程主机环境。

2.4 可选：安装其他 ROS / Isaac ROS 库

建议基于 Isaac ROS 官方镜像制作项目专用镜像，把项目需要的 ROS / Isaac ROS 库写进 Dockerfile。直接在 isaac-ros activate 进入的临时容器里执行 apt install 只适合快速验证；容器停止、重建或清理后，手动安装的包会丢失。

按项目需要在 Isaac ROS 容器内安装额外库。机械臂规划常用 MoveIt 和 Isaac ROS cuMotion：

sudo -i
apt clean
rm -rf /var/lib/apt/lists/*
apt update
apt install -y ros-jazzy-moveit ros-jazzy-isaac-ros-cumotion
exit

确认 package 可见：

ros2 pkg list | grep -E 'moveit|cumotion'

确认结果：能看到 moveit、moveit_ros_planning_interface、isaac_ros_cumotion 等 package 名称。

常见可选库：

完整 Isaac ROS 包列表见官方索引：Repositories and Packages。

如果只做普通 ROS 2 Python 节点开发，可以跳过这一步。

2.5 创建最小 Python 节点验证开发链路

远程主机、Docker 容器和 ROS 2 都验证通过后，再创建一个最小 Python ROS 2 package，确认 workspace、colcon 构建、Python 节点注册和 ros2 run 都能正常工作。

如果还不在 Isaac ROS 容器中，先执行：

cd $ISAAC_ROS_WS
isaac-ros activate

在容器中创建最小 package：

cd ${ISAAC_ROS_WS}/src
ros2 pkg create py_hello --build-type ament_python --dependencies rclpy

这条命令会在 src 目录下创建一个名为 py_hello 的 ROS 2 package：

• py_hello：package 名称，后续运行时会用到，例如 ros2 run py_hello hello_node。
• --build-type ament_python：说明这是一个 Python package，使用 ROS 2 的 ament_python 构建方式。
• --dependencies rclpy：声明这个 package 依赖 ROS 2 Python 客户端库，后面的节点会通过它创建 node、timer、logger 等对象。

编辑 ${ISAAC_ROS_WS}/src/py_hello/py_hello/hello_node.py：

import rclpy
from rclpy.node import Node


class HelloNode(Node):
    def __init__(self):
        super().__init__("hello_node")
        self.timer = self.create_timer(1.0, self.say_hello)

    def say_hello(self):
        self.get_logger().info("Hello from Isaac ROS remote dev")


def main():
    rclpy.init()
    node = HelloNode()
    try:
        rclpy.spin(node)
    finally:
        node.destroy_node()
        rclpy.shutdown()


if __name__ == "__main__":
    main()

再编辑 ${ISAAC_ROS_WS}/src/py_hello/setup.py，在 entry_points 的 console_scripts 下加入节点入口：

entry_points={
    "console_scripts": [
        "hello_node = py_hello.hello_node:main",
    ],
},

构建并运行：

cd ${ISAAC_ROS_WS}
colcon build --symlink-install --packages-select py_hello
source install/setup.bash
ros2 run py_hello hello_node

看到下面的日志就说明最小开发链路跑通：

[INFO] [hello_node]: Hello from Isaac ROS remote dev

这一步用到的三个命令分别负责：

• colcon build --symlink-install --packages-select py_hello：只构建 py_hello。--symlink-install 让 Python 脚本和 launch 文件以符号链接进入 install/，便于开发时改完直接跑。
• source install/setup.bash：把当前 workspace 加载到这个 shell，让 ROS 2 找到刚构建出来的 package 和节点。
• ros2 run py_hello hello_node：运行 py_hello 包里注册的 hello_node 节点。

launch 文件用于一次性启动多个 ROS 2 节点、设置参数、配置 topic remap 和组织启动流程。本文的最小 hello 示例只启动一个节点，所以使用 ros2 run；真实 Isaac ROS demo 或机器人应用通常使用 ros2 launch your_package your_launch.py 启动整组节点。

3. 准备 macOS 端开发环境

PyCharm 远程开发相关能力以 JetBrains 官方文档为准：

• Connect to a remote server from PyCharm
• Configure an interpreter using SSH
• Configure an interpreter using Docker
• Remote Debugging with PyCharm

3.1 安装本地工具并配置 SSH

macOS 端安装这些工具即可：

• PyCharm Professional
• Git
• SSH key

验证本地工具：

git --version
ssh -V

如果使用 JetBrains Gateway，也可以安装；如果直接用 PyCharm 内置 Remote Development，则不需要单独安装 Gateway。

确认结果：git --version 和 ssh -V 都能正常输出版本信息。

3.2 验证 SSH 免密登录

把 macOS 的 SSH key 加到远程主机：

ssh-copy-id user@remote-host

验证免密登录：

ssh user@remote-host

如果没有 ssh-copy-id，也可以手动把 ~/.ssh/id_ed25519.pub 追加到远程主机的 ~/.ssh/authorized_keys。

确认结果：执行 ssh user@remote-host 后无需输入密码，能直接进入远程主机 shell。

3.3 使用 Remote Development 打开 Isaac ROS workspace

推荐使用 PyCharm Remote Development。PyCharm 后端运行在远程主机，macOS 只显示 UI，对大型 ROS 2 workspace 更稳定。

基本步骤：

1. 打开 PyCharm。
2. 选择 Remote Development。
3. 选择 SSH。
4. 填写远程主机地址、用户名、SSH key。
5. 在远程主机上执行 echo $ISAAC_ROS_WS，拿到 workspace 的实际路径。
6. 在 PyCharm 中选择该实际路径，例如 /home/user/workspaces/isaac_ros-dev。
7. 等待 PyCharm 在远程主机安装 IDE backend。

打开后，在 PyCharm Terminal 中验证当前目录和环境：

pwd
cd $ISAAC_ROS_WS
isaac-ros activate

确认结果：PyCharm Terminal 位于远程主机，isaac-ros activate 能进入 Isaac ROS Docker 开发环境。

可选方式：SSH Interpreter + Deployment，适合小型 Python 脚本。本文主线不采用该方式；SSH Interpreter 选择的是远程宿主机 Python，而 Isaac ROS 节点运行在容器内，两者环境可能不一致。

3.4 确认运行方式和解释器策略

Isaac ROS 相关命令统一从 PyCharm Terminal 进入 Docker 开发环境后执行：

cd $ISAAC_ROS_WS
isaac-ros activate

进入容器后验证：

echo $ROS_DISTRO
ros2 --help

构建过当前 workspace 后，再加载 workspace 环境：

source ${ISAAC_ROS_WS}/install/setup.bash

echo $ROS_DISTRO 能输出 ROS 发行版，ros2 --help 能输出帮助信息，构建后的 package 可以在 source workspace 后被 ros2 run 或 ros2 launch 找到。

PyCharm 的 Python Interpreter 可以先选择远程宿主机 Python，用于索引和基础补全；真正运行 Isaac ROS 节点、colcon build、ros2 run、ros2 launch 时，以 PyCharm Terminal 中的 isaac-ros activate 环境为准。

3.5 配置索引和排除目录

在 Project 视图中，把这些目录标记为 Sources Root：

• ${ISAAC_ROS_WS}/src
• 自己维护的 ROS 2 package 目录
• 生成的 Python package 源码目录

同时排除这些目录：

• build/
• install/
• log/
• .cache/
• rosbag 数据目录
• 模型权重目录

Project 视图中源码目录能正常索引，build/、install/、log/ 和大数据目录不会参与索引。Isaac ROS workspace 经常包含 rosbag、模型、TensorRT engine 和构建缓存，不排除会明显拖慢 PyCharm。

4. Python 节点远程调试

调试原则：节点仍在 Isaac ROS 容器中用 ros2 run 或 ros2 launch 启动，PyCharm 只接收 debug 连接。

4.1 配置 PyCharm Debug Server

在 PyCharm 中创建 Python Debug Server 配置：

1. 打开 Run | Edit Configurations。
2. 新建 Python Debug Server。
3. 端口填写 5678。
4. 配置 path mappings：容器内代码路径映射到 PyCharm 打开的 workspace 路径。例如容器内 /workspaces/isaac_ros-dev 映射到远程主机 ${ISAAC_ROS_WS} 对应的实际路径。
5. 启动这个 debug server。

确认结果：PyCharm 进入等待连接状态，端口为 5678。

4.2 确认容器能访问 Debug Server

使用 Remote Development 时，PyCharm 后端在远程主机上，Debug Server 也在远程主机侧。Isaac ROS 容器通常使用 host 网络，节点可以直接连接：

127.0.0.1:5678

如果你使用的是 macOS 本地 PyCharm，而不是 Remote Development，需要从 macOS 另开一个终端建立反向隧道：

ssh -N -R 5678:127.0.0.1:5678 user@remote-host

保持这个 SSH 进程不退出。远程侧访问 127.0.0.1:5678 时，会转发到 macOS 上的 PyCharm Debug Server。

4.3 在 Isaac ROS 容器内安装调试包

在 PyCharm Terminal 中进入容器：

cd $ISAAC_ROS_WS
isaac-ros activate

安装调试包。优先使用 PyCharm Python Debug Server 配置页生成的精确安装命令，保证 pydevd-pycharm 版本与当前 PyCharm 匹配。形式通常如下：

python3 -m pip install "pydevd-pycharm~=PYCHARM_VERSION"

如果容器重建或清理过，需要重新安装。

4.4 在节点中接入调试器

在需要调试的 Python 节点入口附近临时加入：

import pydevd_pycharm

pydevd_pycharm.settrace(
    "127.0.0.1",
    port=5678,
    stdoutToServer=True,
    stderrToServer=True,
    suspend=False,
)

如果容器不是 host 网络，把 127.0.0.1 替换成容器能访问到的远程主机地址。

启动节点：

source ${ISAAC_ROS_WS}/install/setup.bash
ros2 run py_hello hello_node

确认结果：节点启动后连接到 PyCharm，断点可命中，stdout/stderr 能在 Debug 窗口看到。

调试完成后，删除 settrace 代码，或用环境变量保护，避免提交到生产代码。

5. ROS 图形工具怎么处理

macOS 上直接运行远程 RViz 稳定性和交互体验都较差。建议按优先级选择：

1. 在远程 Linux 桌面上运行 RViz。
2. 使用 Foxglove 通过网络查看 ROS 2 topic。
3. 使用 XQuartz / X11 forwarding，只作为临时方案。

如果只是看 topic、service、node 和日志，优先用命令行：

ros2 node list
ros2 topic list
ros2 topic echo /topic_name
ros2 service list
ros2 bag record /topic_name