# [component_container_isolated]：加载组件失败：找不到名为'my_pkg::MyComponent'的类：库中无匹配类

- **ID:** `ros2/component-container-mismatch`
- **领域:** ros2
- **类别:** module_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

组件类未使用RCLCPP_COMPONENTS_REGISTER_NODE宏注册，或者库未正确构建/链接，导致容器在运行时无法实例化它。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| ROS2 Humble | active | — | — |
| ROS2 Iron | active | — | — |
| ROS2 Jazzy | active | — | — |

## 解决方案

1. ```
   确保组件源文件包含注册宏：'RCLCPP_COMPONENTS_REGISTER_NODE(my_pkg::MyComponent)'，并且CMakeLists.txt使用'add_library'，必要时包含'ament_target_dependencies'和'pluginlib_export_plugin_description_file'。
   ```
2. ```
   检查库导出：'nm -C libmy_component.so | grep MyComponent'以查看符号是否存在。如果不存在，使用'colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug'重新构建并检查缺失的依赖。
   ```
3. ```
   验证组件的插件描述XML文件（如'my_component_plugins.xml'）格式正确，并在'package.xml'的<export>部分中引用。
   ```

## 无效尝试

- **Adding the component source file to a different package's CMakeLists.txt without proper registration** — The class must be registered in the same library where it is built, using the correct macro. Moving files without registration does not help. (90% 失败率)
- **Manually loading the library with 'dlopen' in the container to verify it exists** — The library may exist but the class registration may still be missing. This does not fix the registration issue. (60% 失败率)