21 Apr 2026 20 min read

WSL python 開發環境設定

對於AI相關的開發在Linux系統的生態相比Windows來的豐富，因此Linux環境的操作是一個需要養成的習慣，在實務操作層面會輕鬆、便利、快速許多。

因應使用的便利性和設備的通用性，這裡演示透過Windows上的Ubuntu子系統 (WSL) 結合miniconda構成所需要的開發環境。這套架構將 Windows 的易用性與 Linux 的開發者生態結合，特別適合需要隔離環境、高度硬體最佳化（例如編譯 C/C++ 或本地端 AI 模型）的開發情境。

如果使用原生安裝的Linux發行版，可以跳過有關WSL的段落，從開始閱讀

環境架構：

=================================================================
                [ Windows 作業系統 (本機端) ]
=================================================================
  
  +-----------------------------------------------------------+
  |  Visual Studio Code (前端 UI)                             |
  |                                                           |
  |  [ WSL 擴充套件 (Remote - WSL) ] <--- 負責建立溝通橋樑      |
  +--------------------------|--------------------------------+
                             |
                             |
=============================|===================================
                       [ Container ]
=============================|===================================
                             v
=================================================================
              [ WSL 子系統 (Ubuntu / Linux 端) ]
=================================================================
  
  +----------------------------------------------------------+
  |  VS Code Server                                          |
  |  - 自動由 Windows 安裝啟動                                |
  |  - 實際執行 Linter、CMake Tools 功能                      |
  |  - 直接存取 Linux 檔案系統，將結果回傳給 Windows 顯示       |
  |                                                          |
  |  +----------------------------------------------------+  |
  |  | Miniconda (專案獨立的虛擬環境, 例如 env_dev)         |  |
  |  |                                                    |  |
  |  |  [ 專案原始碼 ] <----- Linter 進行語法檢查           |  |
  |  |                                                    |  |
  |  |  +----------------------------------------------+  |  |
  |  |  | 測試工具                                      |  |  |
  |  |  | - CMake：讀取設定，自動生成 Makefile 等編譯腳本 |  |  |
  |  |  | - build-essential：包含 GCC/G++ 與 Make       |  |  |
  |  |  | - Python：執行環境                            |  |  |
  |  |  +----------------------------------------------+  |  |
  |  +----------------------------------------------------+  |
  +----------------------------------------------------------+

以下拆解並介紹這些元件在開發環境中扮演的角色與運作原理：

元件介紹

1. 基礎運行環境：WSL (Windows Subsystem for Linux)

簡介：由微軟推出的子系統，讓開發者可以直接在 Windows 上原生執行 Linux 環境（如 Ubuntu），無須設定雙系統，也不必承擔完整虛擬機的龐大系統資源消耗。
扮演角色：底層基礎建設。大部分的開源專案、編譯工具鏈對 Linux 的相容性與效能都遠優於 Windows。WSL 讓開發者能直接使用 Linux 核心，享有原生的 bash、檔案系統操作以及極高的 I/O 效能。
參考資源：Microsoft: 什麼是 Windows Subsystem for Linux (WSL)？

2. 環境與套件隔離：Miniconda

簡介：輕量級的環境與套件管理工具。相較於包含大量預載套件的 Anaconda，Miniconda 預設只包含 Python、conda 管理員以及最基礎的相依性，主打「按需安裝」。
扮演角色：開發環境的隔離艙。如同在伺服器上使用 Docker 隔離服務一樣，Miniconda 可以為不同的專案建立獨立的虛擬環境（例如 env_A 用 Python 3.10，env_B 用 Python 3.11），避免套件版本衝突。它不僅能管理 Python 套件，也能安裝與管理許多 C/C++ 的底層函式庫。
參考資源：Miniconda 官方文件

3. 編譯工具鏈：build-essential 與 CMake

簡介：
- build-essential：這是 Debian/Ubuntu 系統中的一個「大補帖」套件包，安裝它等於一口氣裝好了 C/C++ 編譯器（GCC/G++）、make 工具以及其他必備的標準函式庫。
- CMake：一個跨平台的「建置系統生成器」。它本身不編譯程式碼，而是讀取你寫的 CMakeLists.txt 檔案後，自動幫你產生對應平台所需的編譯腳本（例如 Linux 下的 Makefile）。
扮演角色：工廠的生產線。當你撰寫 C/C++ 專案，或是需要從原始碼編譯帶有高度硬體指令集優化的套件時，這套組合就是業界標準的編譯流程。
參考資源：CMake 官方文件：Getting Started

4. 開發介面與防呆機制：VS Code + WSL Extension + Linter

簡介：
- VS Code：輕量但功能強大的程式碼編輯器。
- WSL Extension：微軟官方的擴充套件，這項技術稱為「遠端開發 (Remote Development)」。
- Linter：靜態程式碼分析工具（例如 C/C++ 常用的 clang-tidy 或 Python 的 flake8）。它會在程式碼執行前，檢查語法錯誤、潛在的 Bug 或不符合排版規範的地方。

扮演角色：開發儀表板。透過 WSL 擴充套件，VS Code 的「UI 介面」運作於 Windows 系統上，但「編輯的檔案、執行的指令、編譯的過程」全部都在 WSL 的 Linux 環境裡進行。配合 Linter 能在打字的當下就即時標記錯誤，大幅提升開發效率。

參考資源：VS Code 官方教學：Using C++ and WSL in VS Code

當這套環境架設完畢後，開發流程如下：

在 Windows 打開 VS Code，透過擴充套件連線進入 WSL (Ubuntu)。
在 VS Code 的終端機內，啟動 Miniconda 的專屬虛擬環境。
撰寫程式碼，過程中 Linter 即時除錯與維持排版。
寫好後，透過 CMake 產生編譯設定，並交由 build-essential (GCC/Make) 將程式碼編譯成執行檔。

1. 安裝 WSL & Ubuntu

微軟已經將 WSL 的安裝大幅簡化，現在只需要一行指令。預設情況下，這行指令會自動幫你下載並安裝最新版的 Ubuntu 發行版。

在 Windows 搜尋列輸入 PowerShell。
在「Windows PowerShell」上點擊右鍵，選擇 「以系統管理員身分執行」。
在終端機視窗中輸入以下指令並按 Enter：

wsl --install

等待進度條跑完。這個過程會自動啟用所需的 Windows 虛擬化功能、下載 Linux 核心，並安裝 Ubuntu。

提醒： 在 Linux 終端機輸入密碼時，畫面上完全不會顯示任何星號或字元。請直接輸入完畢後按 Enter 即可。

出現這個畫面代表已安裝成功，可以重啟裝置了

安裝完成後，請重新啟動你的電腦（這一步不可省略，否則部分底層核心功能不會正式啟用）。

其他情形說明

A. 如果有指定的安裝版本或者是需要其他發行版，可以透過下列指令安裝

# 透過這行指令查詢目前可安裝的Linux發行版
wsl --list --online

# 加上參數明確表示安裝的版本
wsl --install <Distro>

以下展示2026/04可安裝的版本

B. 如果出現下列訊息，代表未開啟虛擬化(VT-d 或 SVM)功能，開啟方式依主機板而定

2. 將 VS Code 連結至 WSL

重啟之後可以直接點擊 "Ubuntu" 程式，會直接進入專門的CLI介面

打開 Windows 上的 VS Code。點擊左側邊欄的「延伸模組 (Extensions)」圖示（或是按下 Ctrl+Shift+X）。
搜尋並安裝微軟官方推出的 WSL 擴充套件。
安裝完成後，請回到剛才的 Ubuntu 終端機視窗，輸入code並按 Enter。

第一次執行時，Ubuntu 會在背景自動下載並安裝 VS Code Server，請給它一點時間下載。

Windows 上的 VS Code 會自動開啟一個新視窗。可以看到編輯器左下角的狀態列出現類似 >< WSL: Ubuntu 的藍色或綠色標籤。

日後開啟 WSL 的 VS code ，都可以直接輸入 code 打開。

雖然你已經在 Windows 裝了 VS Code，但有些套件必須安裝在「WSL 裡面」才能正確運作。

回到 VS Code 的 Extensions (Ctrl+Shift+X)。
搜尋並安裝以下套件，安裝後會自動出現在 "WSL: Ubuntu - Installed"：

C/C++ Extension Pack (由 Microsoft 推出，包含 C++、CMake 等支援)。
Python (搭配 Miniconda 使用)。
Error Lens (optional，能將錯誤訊息直接顯示在程式碼行尾)。

3. 安裝編譯工具

在安裝之前，先說明 Linux CLI 安裝/更新軟體的方式。

# 更新軟體資訊
sudo apt update

# 升級軟體包
sudo apt upgrade

# 安裝指定軟體
apt install <name>

apt 套件更新工具

APT (Advanced Packaging Tool) 是 Debian、Ubuntu 等基於 Debian 的 Linux 發行版中強大的套件管理工具。它能自動處理軟體包的依賴關係，提供搜尋、安裝、升級和移除軟體的功能，需使用root帳號或 sudo 權限

apt update : 用於更新本地軟體套件資料庫的指令。通常在 upgrade 或 install 前執行，以得知哪些軟體有新版本可用。執行後不會升級任何軟體包。
apt upgrade : 用於更新本地軟體套件包的指令。在執行後會需要使用者輸入 yes 確認升級。如果需要全自動運行可以在後面增加 -y 引數。
apt install <name> : 安裝指定軟體包。可以一次安裝多個套件，只需要在名稱部分以空格區分 (例如 <name1> <name2> <name3> )
apt remove <name> : 移除指定軟體包但不移除其設定檔。
apt purge <name> : 完全移除指定的軟體包。
apt autoremove :自動移除不需要的其他軟體相依之套件。

原則上安裝 build-essential, cmake, gdb(optional) 就可以應付這邊的環境大部分的需求。這些是在 Linux 下開發 C/C++ 的標準配備。

編譯工具介紹

這三個工具在 C/C++ 的開發過程中扮演著截然不同但互相依賴的角色。以下是它們的詳細介紹：

1. build-essential

它其實不是一個單一的軟體，而是 Ubuntu/Debian 系統中的一個「懶人包」。當你安裝它時，系統會一次幫你裝好 C/C++ 開發最核心的底層工具。

包含：
- GCC / G++： 編譯器
- Make： 自動化執行工具。當你的專案有很多個程式碼檔案時，它會根據一份名為 Makefile 的清單，自動呼叫 GCC 幫你把所有檔案依照正確的順序編譯並打包起來。
- C/C++ 標準函式庫 (libc 等)： 提供寫程式時會用到的基本功能，像是 printf 或 std::cout（印出文字到螢幕上）。
功能： 負責將程式碼轉換成執行檔。

2. cmake

當專案越來越大，可能有幾十個檔案、需要連結外部的第三方套件，這時候要人工去寫那份給 Make 看的 Makefile 清單會容易出錯。CMake 就是為了解決這個問題而誕生的。

目標： 只需要寫一份非常簡單、易讀的設定檔（叫做 CMakeLists.txt），告訴 CMake 你的專案叫什麼名字、有哪些程式碼檔案。
作用：它會根據目前的作業系統（Windows、Linux 或 macOS），自動幫你生成對應的底層編譯清單。在 Linux 下，它就是幫你自動生出那份複雜的 Makefile，然後交給 build-essential 執行。
功能： 本身不負責編譯，而是負責規劃流程，並發配工作清單給底層的工具。

3. gdb

程式寫完並且編譯成功後，不代表它能完美運作。有時候程式執行到一半會突然崩潰或者算出來的結果跟預期的不一樣。這時候就需要 GDB（GNU Debugger）。

目標：把正在執行中的程式「暫停」的除錯器。
功能：
- 設定中斷點 (Breakpoints)： 讓程式跑到第 n 行時自動暫停。
- 單步執行 (Step-by-step)： 讓程式碼一行一行慢慢跑，你可以像看慢動作重播一樣觀察它。
- 變數監控： 程式暫停時，你可以隨時查看裡面的變數 x 或 y 現在的數值是多少。

開發工作流

在實際的開發情境中，它們會按照以下順序配合：

寫程式： 你在 VS Code 裡面寫好了 main.cpp。
規劃流程 (CMake)： 你執行 cmake 指令，它讀取你的設定，幫你生成一份 Makefile。
開始編譯 (build-essential)： 你執行 make 指令，Make 工具會根據清單，呼叫 GCC 把你的 main.cpp 變成可以執行的檔案 app 。
檢查 Bug (GDB)： 執行 app 後發現結果不對，你啟動 gdb 來載入這個程式，一行一行檢查，抓出寫錯的邏輯，然後回到步驟 1 修改程式碼。

具體安裝流程如下：

更新系統套件資料

sudo apt update

安裝編譯器與工具

sudo apt install build-essential cmake gdb -y

等待進度條完成後，即可正常使用。

4. 安裝 Miniconda

Miniconda 的核心是 conda（套件與虛擬環境管理工具），和 Anaconda 相似，最大的差異在於「預先安裝的內容多寡」與「檔案大小」。

Anaconda vs Miniconda

1. Miniconda 是什麼？

Miniconda 是一個輕量級的 conda 安裝程式，裡面只有最基本的基礎設施。它只安裝了：

Python 程式語言
conda 套件管理員
少數維持系統運作的必要套件（例如 pip、zlib 等）

因為它非常乾淨，所以你需要什麼套件（例如 NumPy、Pandas），都必須自己手動輸入指令來安裝（例如：conda install numpy）。

2. Anaconda 與 Miniconda 的差異

Anaconda 則是一個完整版。除了 Python 和 conda 之外，它還預先幫你安裝了數百個資料科學、數學計算最常用的套件，並附帶一個友善的圖形化介面（Anaconda Navigator）。

無論安裝哪一個，兩者使用的 conda 指令完全一模一樣，也連接到同一個套件庫，但原則上還是建議使用 pip。

選擇重點

這取決於使用習慣和電腦資源：

a. 建議選擇 Miniconda，因為:

硬碟空間的考量。
已經熟悉指令操作。
程式碼潔癖，只想要安裝自己真正用得到的套件，不喜歡系統裡有一大堆用不到的軟體。
您要在伺服器或容器中部署環境。

b. 建議選擇 Anaconda，因為:

屬於初學者。
不想花時間去搞懂每個套件要怎麼安裝、處理套件之間的相依性問題，希望裝好就能直接開始寫程式。
喜歡使用圖形化介面來開啟 Jupyter Notebook 或管理虛擬環境。

在WSL中的環境，需要透過指令下載 Linux 版的 Miniconda 並安裝。

下載 Miniconda 安裝腳本：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

允許腳本執行：

系統為了保護裝置，一般來說都會不允許腳本直接運行需要使用者手動允許執行，透過 chmod 指令:

chmod 744 ./Miniconda3-latest-Linux-x86_64.sh

chmod 指令介紹

chmod (change mode) 是 Linux/Unix 系統中用於更改檔案或目錄存取權限的指令。它透過定義擁有者（User）、群組（Group）和其他使用者（Others）對檔案的權限來控管安全性，是一種基於角色的存取控制 (Role-Based Access Control, RBAC. 不直接將權限賦予使用者，而是將權限指派給「角色」) 。

核心語法： chmod <option> <mode> <file>
選項：

-R (Recursive): 遞迴處理，將權限套用到目前目錄下的所有檔案與子目錄。

模式設定方法

A. 數字模式 (octal，最推薦)

對於擁有者、群組和其他，將各自的權限相加：read = 4, write = 2, execute = 1。

7 : 讀&寫&執行 (rwx)
6 : 讀&寫 (rw-)
5 : 讀&執行 (r-x)
4: 唯讀 (r--)

範例：

chmod 755 file: 擁有者可讀寫執行，群組/其他僅可讀執行。
chmod 644 file: 擁有者可讀寫，群組/其他僅可讀。
chmod 777 file: 所有人都可讀寫執行。

B. 符號模式

對象: u (User/擁有者), g (Group/群組), o (Others/其他), a (All/全部)。
操作: + (增加), - (減少), = (設定)。
權限: r (Read), w (Write), x (Execute)。

範例：

chmod +x file: 賦予所有人執行權限。
chmod g+w file: 增加群組成員寫入權限。
chmod o-w file: 取消其他使用者寫入權限。
chmod u=rwx,go=rx file: 擁有者全部權限，群組/其他讀取和執行。

對象：

只有檔案所有者和超級使用者（root）可以修改權限。若權限不足，請加上 sudo。

執行安裝腳本：

# 在腳本存放的位置(原則上不需要特別調整)
./Miniconda3-latest-Linux-x86_64.sh

安裝過程中會請你按 Enter 閱讀條款，最後輸入 yes 同意。
採用預設的安裝路徑（也就是你的家目錄 /home/<your_name>/miniconda3），直接按 Enter。
當它問你是否要執行 conda init 時（Do you wish the installer to initialize Miniconda3 by running conda init? ），請輸入 yes。

腳本會自動安裝，出現以下畫面即表示安裝完成

直接關閉目前的終端機分頁，再開一個新的。如果你看到命令列前方出現 (base) 字樣，就代表安裝成功了。

刪除安裝檔（optional）：

rm Miniconda3-latest-Linux-x86_64.sh

miniconda 虛擬環境使用

這個虛擬環境實際上屬於沙盒。建立虛擬環境的好處是可以為專案 A 裝 Python 3.10 和一套套件，為專案 B 裝 Python 3.12 和另一套套件，它們彼此完全隔離。

1. 建立新的沙盒

假設我們要建立一個名為 my_cpp_py_env 的環境，並且指定安裝 Python 3.11 版本，請輸入以下指令：

conda create --name my_cpp_py_env python=3.11 -y

--name 可以縮寫為 -n。
python=3.11 是指定安裝版本。
-y 代表自動同意安裝，中途就不會再問你 Proceed ([y]/n)? 了。
如果出現 CondaToSNonInteractiveError: Terms of Service have not been accepted for the following channels.，請直接輸入

conda tos accept --override-channels --channel <終端機顯示的URL>

2. 進入沙盒

環境建立好之後，它預設是關閉的。需要「啟動」並進入它：

conda activate my_cpp_py_env

執行這行指令後，你會發現終端機最前面的字樣從 (base) 變成了 (my_cpp_py_env)。代表成功進入沙盒環境，接下來用 pip 或 conda 安裝的任何東西，都只會存在這個沙盒裡。

3. 查看有哪些沙盒

如果需要確認自己在這個裝置建過哪些環境，可以使用這個指令列出清單：

conda env list

(清單中帶有 * 星號的，就代表你目前正在使用的沙盒。)

4. 離開沙盒

透過以下指令退出目前的沙盒回到最外層的 (base)：

conda deactivate

5. 刪除沙盒

如果這個專案結束了，或者環境壞了想重來，可以把它整個刪掉（請先確保已 deactivate 退出了該環境）：

conda env remove --name my_cpp_py_env -y

如何讓 VS Code 知道你切換了沙盒？

雖然你在終端機裡 conda activate 了，但 VS Code 的編輯器（和你的 Linter）有時候還在舊的環境。需要手動指引它：

在 VS Code 裡打開任何一個 .py Python 檔案。
按下快捷鍵 Ctrl + Shift + P 打開命令。
輸入或選擇 Python: Select Interpreter (選取直譯器)。
在跳出的選單中會看到你剛剛建立的 my_cpp_py_env，點擊它

這樣一來，VS Code 的智慧提示、Linter 和右下角的執行按鈕，就全部都會對齊這個新沙盒的標準了。

5. 確認安裝

讓我們確認所有東西都裝好了。在終端機輸入：

gcc --version (應該看到 GCC 的版本號)
cmake --version (應該看到 CMake 的版本號)
conda --version (應該看到 Conda 的版本號)

6. Python 的 Linter

目前 Python 界最受歡迎、速度極快的 Linter 叫做 Ruff。我們可以直接透過 VS Code 延伸模組來安裝，不須額外設定。

步驟 1：安裝 VS Code 擴充套件

打開 VS Code 左側的「延伸模組 (Extensions)」。
搜尋 Ruff（由 Astral Software 推出）。
安裝後確認出現在 "WSL: Ubuntu - Installed"。

步驟 2：設定儲存時自動排版與檢查

讓 Linter 在你每次按下 Ctrl + S 儲存時，自動幫你整理程式碼：

按下 Ctrl + , 打開設定。
搜尋 Format On Save，並將 Editor: Format On Save 打勾。

接著搜尋 Default Formatter，將 Editor: Default Formatter 的下拉式選單改為 Ruff。

步驟 3：設定「存檔即自動修復」的配置

Ruff 最強大的地方在於它不僅能「發現」問題，還能「自動解決」問題（例如自動刪除沒用到的 import、自動排版引號和縮排）。最俐落的做法是直接修改 VS Code 的底層設定檔：

按下快捷鍵 Ctrl + , 打開設定。
VS Code 畫面的右上角有一個一份文件上面帶有箭頭或括號的小圖示（滑鼠移過去會顯示 「開啟設定 (JSON)」 或 Open Settings (JSON)），點擊它。

這會打開一個 settings.json 檔案。請在最外層的大括號 {} 裡面，貼上這段專門給 Python 的設定：

"[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    }

如果 settings.json 裡面原本就有其他東西，記得在貼上這段程式碼的前一行尾加上逗號 , 來分隔 ( json 語法)。

儲存並關閉這個設定檔。

這套流程建立好之後，就具備一個非常方便且完善的開發環境，同時可以省下大量排版跟除錯的時間。