colcon build 與依賴管理

2026-07-18
  • ros2
  • colcon
  • rosdep
  • build

問題定義

上一節我們建立了一個空的套件骨架，但還沒有真正「編譯」過它。這一節要解決兩個問題：怎麼把套件編譯成可執行的成果，以及怎麼確保套件宣告的依賴都有裝好——這兩件事沒做對，之後 ros2 run 會直接找不到你的節點。

核心概念說明

colcon build 在做什麼

colcon build 會掃描 src/ 底下所有套件，依照它們宣告的依賴關係排序，逐一編譯，並把結果放到 install/ 資料夾。對 Python 套件來說，「編譯」主要是把檔案複製（或連結）到 install/，讓 ROS2 知道去哪裡找你的節點；對 C++ 套件來說，就是實際呼叫 CMake 編譯原始碼。

rosdep：自動安裝套件依賴

還記得上一節 package.xml 裡的 <depend> 標籤嗎？當你的套件依賴其他 ROS2 套件（例如 rclpy、sensor_msgs）或系統函式庫時，rosdep 可以讀取這些宣告，自動幫你用 apt 裝好對應的東西，不用自己一個一個查名稱手動安裝。

實作範例

1. 安裝套件宣告的依賴

在工作空間根目錄執行：

bash
cd ~/ros2_ws
rosdep install --from-paths src -y --ignore-src
  • --from-paths src：掃描 src/ 底下所有套件的 package.xml
  • --ignore-src：跳過「本身也在 src/ 裡的套件」，只裝外部系統依賴
  • -y：自動確認安裝，不用每個都手動按 y

預期輸出

如果所有依賴都已經裝好：

text
#All required rosdeps installed successfully

如果有依賴需要安裝，會看到類似：

text
executing command [sudo apt-get install -y ros-lyrical-rclpy]
...
#All required rosdeps installed successfully

2. 編譯工作空間

bash
colcon build --symlink-install

--symlink-install 讓 Python 檔案用符號連結取代複製，之後改 .py 原始碼不用重新 build 就能生效，開發階段強烈建議加上。

預期輸出

text
Starting >>> my_package
Finished <<< my_package [0.84s]

Summary: 1 package finished [1.02s]

如果工作空間裡有多個套件，會看到每個套件各自的建置時間，以及最後的總結：

text
Summary: 5 packages finished [12.3s]

3. 只編譯特定套件（增量編譯）

專案套件一多，每次全部重新編譯會很浪費時間。用 --packages-select 指定只編譯你正在改的套件：

bash
colcon build --symlink-install --packages-select my_package

4. 讓新的編譯結果在目前終端機生效

bash
source install/setup.bash

這一步容易忘記——編譯完成不代表終端機馬上「看得到」你的套件，一定要重新 source 這個工作空間的 setup.bash（跟第 1.2 節 source ROS2 本體的道理一樣）。

常見錯誤與除錯技巧

錯誤一：colcon: command not found

text
bash: colcon: command not found

原因：colcon 屬於 ros-dev-tools，如果你在第 1.2 節安裝時跳過了這個套件，就不會有 colcon 指令。

排除方式：

bash
sudo apt install ros-dev-tools -y

錯誤二：Package 'xxx' not found（執行 ros2 run 時）

text
Package 'my_package' not found

原因：這幾乎每次都是同一個問題——編譯完成後忘記 source install/setup.bash，導致目前的終端機環境還不認識這個新編譯出來的套件。

排除方式：

bash
cd ~/ros2_ws
source install/setup.bash
ros2 pkg list | grep my_package

如果 ros2 pkg list 能找到 my_package，代表環境已經正確載入。注意：每次開新的終端機視窗都要重新 source 一次工作空間的 setup.bash（不只是 ROS2 本體那次）。

小結

rosdep install 負責把套件宣告的依賴裝齊，colcon build 負責把原始碼編譯成可執行成果，source install/setup.bash 讓目前的終端機認得到這些成果。這三個步驟會是你之後每次開發流程的固定三連拍——接下來我們會進入 ROS2 最核心的部分：節點與通訊機制。

延伸閱讀

常見問題

faq_01.log
每次改完程式碼都要重新 colcon build 嗎？
如果用 --symlink-install 建置 Python 套件，改完 .py 檔案通常不需要重新 build，直接執行就會套用最新程式碼。C++ 套件因為需要重新編譯，修改後一定要重新 build。
faq_02.log
colcon build 沒加任何參數，跟加了一堆參數，差在哪？
不加參數會編譯 src 底下所有套件、每次都重新複製檔案到 install。加上 --symlink-install 和 --packages-select 之後，可以只編譯你在改的套件，並且用符號連結取代複製，大幅縮短開發時的等待時間。
faq_03.log
rosdep install 找不到某個依賴怎麼辦？
先確認 rosdep 資料庫是最新的（rosdep update）。如果套件確實存在但 rosdep 回報找不到，通常是 package.xml 裡的依賴名稱拼錯，或這個依賴是比較新/小眾的套件，rosdep 的規則資料庫還沒收錄，這種情況需要手動 apt install。