本文采用知识共享署名 4.0 国际许可协议进行许可，转载时请注明原文链接，图片在使用时请保留全部内容，可适当缩放并在引用处附上图片所在的文章链接。
[TOC]
ROS 2 环境变量总览（按功能模块分类）
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🧭 路径与包发现 |
AMENT_PREFIX_PATH |
/opt/ros/<distro> |
搜索 ROS 2 包的路径（ament index 基础） |
|
COLCON_PREFIX_PATH |
同上 |
colcon 查找已构建包的路径 |
|
ROS_PACKAGE_PATH |
(无) |
兼容 ROS 1 的路径变量，ROS 2 通常不用 |
|
AMENT_INDEX_PATH |
自动生成 |
ament 索引资源查找路径 |
|
PYTHONPATH |
(系统默认) |
Python 模块查找路径（影响 launch 脚本） |
|
LD_LIBRARY_PATH |
(系统默认) |
动态库查找路径，影响共享库加载 |
|
PATH |
(系统默认) |
可执行文件查找路径，影响 ros2 命令 |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| ⚙️ 节点运行与初始化 |
ROS_DOMAIN_ID |
0 |
DDS Domain ID，用于网络隔离 |
|
ROS_NAMESPACE |
(无) |
为所有节点设置默认命名空间 |
|
ROS_ARGS |
(无) |
启动节点时统一注入参数，例如 --ros-args -r foo:=bar |
|
ROS_LOCALHOST_ONLY |
0 |
限制通信仅在本地 loopback（0=禁用，1=启用） |
|
ROS_SECURITY_ENABLE |
false |
是否启用安全通信 (SROS2) |
|
ROS_SECURITY_STRATEGY |
Enforce |
安全策略：Enforce 或 Permissive |
|
ROS_SECURITY_KEYSTORE |
(无) |
指定安全密钥存储路径 |
|
RCUTILS_COLORIZED_OUTPUT |
1 |
控制日志输出是否彩色显示 |
|
RCUTILS_CONSOLE_OUTPUT_FORMAT |
{severity} [{name}]: {message} |
控制日志格式 |
|
RCUTILS_LOGGING_BUFFERED_STREAM |
1 |
是否启用缓冲日志输出 |
|
RCUTILS_LOGGING_USE_STDOUT |
0 |
是否将日志输出到 stdout |
|
RCUTILS_LOGGING_USE_STDERR |
1 |
是否将日志输出到 stderr |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🧩 中间件（RMW 层） |
RMW_IMPLEMENTATION |
rmw_fastrtps_cpp (或 rmw_cyclonedds_cpp) |
指定使用的 RMW 实现 |
|
RMW_LOG_SEVERITY |
Info |
设置 RMW 层日志级别 |
|
RMW_CONNEXT_ENABLE_LOGGING |
0 |
是否启用 RTI Connext 日志 |
|
RMW_FASTRTPS_USE_QOS_FROM_XML |
false |
是否从 XML 文件加载 QoS |
|
RMW_FASTRTPS_USE_QOS_PROFILES_FROM_XML |
(无) |
QoS 配置 XML 路径 |
|
RMW_CYCLONEDDS_URI |
(无) |
CycloneDDS 配置文件路径 |
|
RMW_IMPLEMENTATION_VALIDATE_TOPIC_NAME |
1 |
是否验证话题名称合法性 |
|
ROS_DISABLE_BUILTIN_TOPICS |
0 |
禁用 DDS 内建主题（部分实现支持） |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🪪 参数与 QoS 配置 |
ROS_PARAM_FILE |
(无) |
从指定 YAML 文件加载参数 |
|
ROS_LOG_DIR |
~/.ros/log |
日志文件输出目录 |
|
ROS_LOG_FILENAME_FORMAT |
{datetime}_{pid} |
日志文件名格式 |
|
ROS_AUTOMATIC_DISCOVERY_RANGE |
SUBNET |
CycloneDDS 自动发现范围 |
|
ROS_DISCOVERY_SERVER |
(无) |
DDS discovery server 地址列表 |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🧪 调试与性能分析 |
RCUTILS_LOGGING_MIN_SEVERITY |
Info |
设置最小日志级别 |
|
RCL_ASSERT_RMW_ID_MATCHES |
(无) |
运行时验证 RMW ID 是否匹配 |
|
RCL_LOG_LEVEL |
Info |
RCL 层日志级别 |
|
RMW_TRACING_ENABLE |
false |
是否启用 RMW trace（需编译支持） |
|
RCL_YAML_PARAM_FILE |
(无) |
指定 YAML 参数文件 |
|
RCUTILS_TIME_OVERRIDE_TYPE |
(无) |
时间源重定向（模拟时间/系统时间） |
|
RCUTILS_TIME_OVERRIDE_SOURCE_FILE_PATH |
(无) |
时间源文件路径 |
|
RCL_ENABLE_TOPIC_STATISTICS |
false |
启用话题统计功能 |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🚀 Launch 系统 |
LAUNCH_SERVICE_TIMEOUT |
10s |
LaunchService 启动等待时间 |
|
LAUNCH_LOG_LEVEL |
info |
Launch 框架日志级别 |
|
LAUNCH_CONFIG_PATH |
(无) |
指定自定义配置文件路径 |
|
PYTHONUNBUFFERED |
1 |
Python 输出不缓冲（方便实时日志） |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🌐 网络与发现 |
CYCLONEDDS_URI |
(无) |
CycloneDDS 配置文件路径 |
|
FASTRTPS_DEFAULT_PROFILES_FILE |
(无) |
FastDDS 配置文件路径 |
|
ROS_DISCOVERY_SERVER |
(无) |
指定 discovery server 列表 |
|
ROS_AUTOMATIC_DISCOVERY_RANGE |
SUBNET |
控制节点自动发现范围 |
|
ROS_LOCALHOST_ONLY |
0 |
限制通信在本地 loopback |
|
RMW_FASTRTPS_USE_QOS_FROM_XML |
false |
从 XML 加载 QoS 配置 |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 🔐 安全 (SROS2) |
ROS_SECURITY_ENABLE |
false |
是否启用 SROS2 |
|
ROS_SECURITY_STRATEGY |
Enforce |
安全策略：Enforce / Permissive |
|
ROS_SECURITY_KEYSTORE |
(无) |
密钥存储路径 |
|
ROS_SECURITY_ROOT_DIRECTORY |
(无) |
根目录（用于手动管理） |
| 模块 |
环境变量 |
默认值 |
作用说明 |
| 📦 构建与工具 |
COLCON_LOG_PATH |
~/.colcon/log |
colcon 构建日志路径 |
|
CMAKE_PREFIX_PATH |
(自动设置) |
CMake 查找依赖路径 |
|
AMENT_TRACE_SETUP_FILES |
0 |
打印每个被 source 的 setup 文件 |
|
COLCON_TRACE_SETUP_FILES |
0 |
打印 colcon setup 跟踪 |
🧠 重点总结
| 功能 |
常用变量 |
说明 |
| 包发现 |
AMENT_PREFIX_PATH |
控制包查找路径 |
| 网络通信 |
ROS_DOMAIN_ID / ROS_LOCALHOST_ONLY |
控制 DDS 网络 |
| 中间件选择 |
RMW_IMPLEMENTATION |
选择使用的 DDS 实现 |
| 日志管理 |
ROS_LOG_DIR / RCUTILS_CONSOLE_OUTPUT_FORMAT |
控制日志输出 |
| 安全通信 |
ROS_SECURITY_* |
启用 SROS2 |
| Launch 调试 |
LAUNCH_LOG_LEVEL / PYTHONUNBUFFERED |
控制启动日志行为 |
🧰 实用命令
1
2
3
4
5
|
# 查看当前 ROS 2 环境变量
env | grep -E "ROS_|RMW_|AMENT_|RCUTILS_"
# 查看特定变量值
echo $ROS_DOMAIN_ID
|