VS Code：安裝、Extensions、Git Graph 與常見錯誤

10. Lab 3 續：VS Code 安裝與驗證

什麼是 VS Code？

VS Code 全名是 Visual Studio Code

• Microsoft 開發的輕量、免費、跨平台的程式碼編輯器（Windows、macOS、Linux 都能用）
• 整合開發流程：一站式完成編寫、測試、版本控制
• 支援語言：Python、JavaScript、C++、Go… 等上百種
• 主要功能：
  • 語法高亮（Syntax Highlighting）
  • 自動補全（IntelliSense）
  • Git 版本控制整合
  • 套件擴充（Extensions Marketplace）

什麼是 IDE

IDE = Integrated Development Environment（整合開發環境）

IDE 把寫程式需要的所有工具整合在一個視窗裡：

功能	沒有 IDE	有 IDE
寫程式碼	用記事本	語法高亮 + 自動補全
跑指令	另開 terminal	內建 Terminal
版本控制	另開 terminal 打 git	內建 Git 面板
Debug	加 print 慢慢找	設中斷點、逐行執行
檔案管理	用檔案總管	左側檔案樹

為什麼選 VS Code

特性	說明
免費	Microsoft 出品，完全免費
跨平台	Windows / Mac / Linux 都能用
Extension 生態	上萬個擴充套件（Python / Git / Docker / Remote…）
WSL Remote	Windows 用戶可以直接編輯 WSL 裡的檔案
業界主流	Stack Overflow 調查連續多年排名第一的 IDE

其他常見 IDE：PyCharm（Python 專用）、Jupyter Notebook（適合分析）、Vim/Neovim（進階）。本課統一用 VS Code。

Step 8：安裝 VS Code

如果已經裝了 VS Code，跳到 Step 9。

🪟 Windows：

1. 打開瀏覽器，前往 code.visualstudio.com
2. 點藍色的「Download for Windows」按鈕

📸 截圖 E1：VS Code 官網下載頁面（標出下載按鈕）

3. 執行下載的安裝檔
4. 安裝精靈一路「下一步」，但注意以下畫面：

📸 截圖 E2：安裝精靈的「選擇附加工作」畫面

• 紅框標出「✅ Add to PATH (requires shell restart)」→ 這個一定要勾！
• 紅框標出「✅ Register Code as an editor for supported file types」→ 建議勾

5. 點「安裝」→ 等待 → 完成

🍎 Mac：

brew install --cask visual-studio-code

✅ 預期：安裝完成，沒有錯誤

裝完後在 VS Code 裡設定命令列工具：

1. 打開 VS Code
2. 按 Cmd+Shift+P（開啟命令面板）

📸 截圖 E3：VS Code 命令面板（標出搜尋欄）

3. 輸入 Shell Command
4. 選「Shell Command: Install ‘code’ command in PATH」

📸 截圖 E4：選擇 Shell Command 選項（標出正確選項）

5. 看到「Shell command ‘code’ successfully installed in PATH」

Step 9：安裝 WSL 擴充套件（🪟 Windows 限定）

1. 打開 VS Code
2. 點左邊欄的「Extensions」圖示（四個方塊的圖示）

📸 截圖 E5：VS Code 左邊欄（紅框標出 Extensions 圖示位置）

• 或用快捷鍵 Ctrl+Shift+X

3. 在搜尋欄輸入 WSL

📸 截圖 E6：搜尋結果

• 紅框標出 Microsoft 出的「WSL」擴充套件
• 標注「認明 Microsoft 官方出品，不要裝錯」

4. 點綠色的「Install」按鈕
5. 等安裝完成（幾秒鐘）

✅ 預期：Install 按鈕變成齒輪圖示，表示已安裝

Step 10：用 code . 打開 VS Code

回到 WSL Ubuntu（或 Mac Terminal）：

cd ~/projects
code .

📣 「~ 是家目錄的捷徑。code . 的 . 是『目前資料夾』的意思。」

⚠️ 第一次執行 code .，WSL 會自動下載 VS Code Server（約 30 秒）：

Installing VS Code Server for x64...
Downloading: 100%
Unpacking: 100%

📸 截圖 E7：VS Code 開啟後的完整畫面

• 紅框①標出左下角「WSL: Ubuntu」（Windows）→ 表示 VS Code 正在編輯 WSL 裡的檔案
• 紅框②標出左邊檔案列表（應該看到 hello.txt）
• 紅框③標出 VS Code 標題列（顯示 projects [WSL: Ubuntu]）

✅ 預期：

• VS Code 自動開啟
• 🪟 左下角顯示綠色的「WSL: Ubuntu」
• 檔案列表看到 hello.txt

Step 11：在 VS Code 裡開 Terminal

1. VS Code 上方選單 → Terminal → New Terminal

📸 截圖 E8：Terminal 選單位置

• 或用快捷鍵 Ctrl+`（反引號，在 Esc 下面那個鍵）

📸 截圖 E9：VS Code 下方的 Terminal

• 紅框①標出 Terminal 面板
• 紅框②標出提示符號（應該顯示 ~/projects$）
• 紅框③標出右上角的 shell 類型（bash 或 zsh）

2. 在 Terminal 裡輸入：

cat hello.txt

✅ 預期：顯示 Hello from WSL!

📣 「從現在開始，你可以在 VS Code 裡面做所有事情——寫程式碼、跑指令、看檔案。不用再切換視窗。」

為什麼之前裝的 VS Code 套件和 Python 版本都不存在？

• 因為我們已經透過 WSL 進入 Ubuntu-22.04 的環境了
• 這些都要重新在 Ubuntu-22.04 的環境中安裝
• 確保當前已經進入 Ubuntu-22.04 的環境

💡 VS Code 左下角會顯示 WSL: Ubuntu-22.04，確認你在 WSL 環境裡。Windows 本機裝的套件跟 WSL 裡的是分開的。

---

11. Lab 4：VS Code Extensions + Git + Git Graph

什麼是版本控制

版本控制是追蹤檔案每一次修改的系統。你可以：

功能	沒有版本控制	有版本控制（Git）
保存進度	複製一份 v1、v2、final、final_final	每次 commit 就是一個存檔點
看修改紀錄	不知道誰改了什麼	git log 看完整歷史
復原	找不到舊版本	git checkout 回到任何一個存檔點
團隊協作	用 Email 傳檔案、手動合併	各自改、用 merge 合併
備份	隨身碟、雲端硬碟	push 到 GitHub，任何電腦都能 clone

什麼是 Git

Git 是目前業界最主流的版本控制工具。幾乎所有軟體公司、開源專案都用 Git。

Git 的核心概念是三區模型：

Working Directory    →    Staging Area    →    Repository
  （工作目錄）        git add   （暫存區）    git commit  （本機 repo）
  你正在編輯的檔案              準備好要 commit 的        已保存的歷史紀錄

區域	比喻	操作
Working Directory	你桌上正在做的作業	編輯檔案
Staging Area	把做好的作業放進信封	git add
Repository	把信封投進郵筒（存進歷史）	git commit

本集只做 Git 本機操作（init → add → commit → log）。GitHub（遠端 push/pull）在 EP02 詳細教。

Step 12：安裝 Python Extension

1. 在 VS Code 裡，點左側 Extensions 圖示（四個方塊的圖）
2. 搜尋 Python
3. 找到 Microsoft 官方出的 Python extension（認明作者是 Microsoft）
4. 點綠色 Install 按鈕

✅ 預期：Install 變成齒輪圖示，表示已安裝

📸 截圖 E10：Python extension 搜尋結果（標出 Microsoft 官方、Install 按鈕）

Python extension 提供：語法高亮、自動補全、linting、debug、Jupyter 支援。後續寫 Python 時會大量用到。

Step 13：安裝 Git Graph

1. Extensions 搜尋 Git Graph
2. 找到 Git Graph extension（作者 mhutchie）
3. 點 Install

✅ 預期：Git Graph 已安裝

📸 截圖 E11：Git Graph extension（標出作者和 Install）

Git Graph 的功能：把 commit 歷史畫成視覺化的樹狀圖。比 git log 直覺很多，特別是有分支和合併的時候。

Step 13.5：推薦擴充套件（選裝）

以下是建議安裝的 VS Code 擴充套件，能大幅提升開發效率：

必裝（課程會用到）：

擴充套件	功能	搜尋關鍵字
Python（Microsoft）	Python 語法高亮、自動補全、debug、Jupyter 支援	Python（已在 Step 12 裝）
WSL（Microsoft）	讓 VS Code 連到 WSL 編輯 Linux 檔案	WSL（已在之前裝）
Git Graph	Git commit 歷史視覺化	Git Graph（已在 Step 13 裝）
Jupyter	在 VS Code 裡開 .ipynb Notebook	Jupyter

強烈推薦：

擴充套件	功能	搜尋關鍵字
GitHub Copilot	AI 自動補全程式碼（需 GitHub 帳號，學生免費）	GitHub Copilot
GitHub Copilot Chat	AI 對話問答、解釋程式碼、Debug	GitHub Copilot Chat
Git Graph	Git commit 歷史視覺化（分支圖形化結構）。作者 mhutchie	Git Graph
Git History	查看 git log、檔案歷史、比較 commit。作者 Don Jayamanne	Git History
GitLens	看每一行是誰在什麼時候寫的（git blame 視覺化）。作者 GitKraken	GitLens
Error Lens	錯誤訊息直接顯示在程式碼那一行旁邊	Error Lens

Python 開發實用：

擴充套件	功能	搜尋關鍵字
autopep8	Python 自動排版（PEP 8 格式）	autopep8
Black Formatter	Python 自動排版（另一種風格，業界常用）	Black Formatter
isort	自動排序 Python 的 import 語句	isort
autoDocstring	在函式上方自動產生 docstring 模板	autoDocstring
Pylance	Python 進階型別檢查、更快的自動補全	Pylance

Docker / 設定檔支援：

擴充套件	功能	搜尋關鍵字
ENV	.env 環境變數檔語法高亮	ENV
Better DockerFile Syntax	Dockerfile 語法高亮最佳化	Better DockerFile
YAML	YAML 語法支援（docker-compose.yml 必備）	YAML
TOML Language Support	pyproject.toml 語法支援	TOML
Remote - SSH	連線到遠端 VM 開發（GCP 會用到）	Remote SSH

外觀與體驗：

擴充套件	功能	搜尋關鍵字
Material Icon Theme	檔案圖示美化（資料夾和檔案類型有不同圖示）	Material Icon Theme
One Dark Pro	深色主題，業界很多人用	One Dark Pro
indent-rainbow	縮排用不同顏色標示，Python 的縮排錯誤一眼看出	indent-rainbow
Rainbow CSV	CSV 檔案每欄不同顏色，看資料很方便	Rainbow CSV
TODO Highlight	突顯程式碼中的 TODO、FIXME 標記	TODO Highlight

測試與品質：

擴充套件	功能	搜尋關鍵字
Coverage Gutters	測試覆蓋率直接標示在編輯器行號旁	Coverage Gutters
Code Spell Checker	英文拼字檢查（變數名/註解拼錯會提醒）	Code Spell Checker

📸 截圖 E11.5：推薦擴充套件清單（標出幾個重點套件）

💡 不用一次全裝。先裝 Jupyter + GitHub Copilot，其他的用到再裝。

Ubuntu 內建沒有 pip，無法使用 pip install 安裝套件

Ubuntu 22.04 預設有 Python 3，但沒有 pip。需要手動安裝：

1. 更新套件清單

sudo apt update

2. 安裝 Python 與 pip

sudo apt install python3-pip -y

3. 驗證安裝

pip3 --version

✅ 預期：pip 22.x.x from /usr/lib/python3/dist-packages/pip (python 3.10)

* 如果你想直接用 pip 而不是 pip3，可以建立連結：

sudo ln -s /usr/bin/pip3 /usr/bin/pip

4. 安裝 Jupyter 互動式環境必備套件

pip install ipykernel

5. 安裝爬蟲常用套件

pip install requests beautifulsoup4

Step 13.6：在 VS Code 使用 Jupyter Notebook 開發

Jupyter Notebook 是一種互動式開發環境，可以在同一檔案中結合程式碼、文字說明、圖表與輸出結果。以「cell」為單位執行，可混合 Markdown 與程式碼。

安裝步驟：

1. 在 VS Code 安裝 Jupyter Extension：

   • Extensions 搜尋 Jupyter
   • 找到 Microsoft 官方的 Jupyter extension
   • 點 Install

2. 建立第一個 Notebook：

   • 按 Ctrl+Shift+P（Mac: Cmd+Shift+P）
   • 搜尋 Jupyter: Create New Notebook
   • 選 Python 3 kernel
   • 在第一個 cell 輸入 print("Hello Jupyter!") 按 Shift+Enter 執行

✅ 預期：cell 下方顯示 Hello Jupyter! 📸 截圖 E12：VS Code Jupyter Notebook 介面（標出 cell、執行按鈕、輸出結果）

💡 之後可以用 Jupyter Notebook 做資料分析、畫圖表、寫筆記。期中 MVP 如果用 Colab 做的 .ipynb，也可以直接在 VS Code 裡打開。

Step 14：確認 Git 已安裝

在 VS Code Terminal 裡輸入：

git --version

✅ 預期：git version 2.x.x（版本號不重要，有就好）

❌ 如果看到 command not found：

• 🪟 Windows：WSL Ubuntu 通常內建 Git。如果沒有：sudo apt install git -y
• 🍎 Mac：輸入 git 後系統會提示安裝 Command Line Tools，按安裝即可

Step 15：設定 Git 使用者資訊

Git 每次 commit 都會記錄「誰做的」，所以要先設定使用者名稱和 email：

git config --global user.name "你的英文名字"
git config --global user.email "你的email@example.com"

這個設定只要做一次，之後所有 repo 都會沿用。

確認設定成功：

git config --global --list

✅ 預期：看到 user.name=... 和 user.email=...

Step 16：建立第一個本機 repo

repo = repository（倉庫），就是一個被 Git 追蹤的資料夾。

cd ~/projects
mkdir my-team-project
cd my-team-project
git init

✅ 預期：Initialized empty Git repository in /home/.../my-team-project/.git/

git init 做了什麼？在資料夾裡建了一個隱藏的 .git/ 目錄，所有版本歷史都存在裡面。你可以用 ls -la 看到它。

Step 17：建立 README 並完成第一次 commit

README.md 是每個專案的「說明書」，放在根目錄，GitHub 會自動渲染顯示。

echo "# My Team Project" > README.md

查看目前 Git 狀態：

git status

✅ 預期：看到 Untracked files: README.md（Git 還沒追蹤這個檔案）

加入暫存區：

git add README.md
git status

✅ 預期：看到 Changes to be committed: new file: README.md（準備好要 commit 了）

建立第一個 commit：

git commit -m "init project readme"

✅ 預期：[master (root-commit) abc1234] init project readme，1 file changed, 1 insertion(+)

看 commit 歷史：

git log

✅ 預期：看到你的 commit（包含 hash、作者、時間、訊息）

按 q 離開 git log 畫面。

Step 18：用 VS Code Source Control 看 Git 狀態

1. 在 VS Code 裡，點左側 Source Control 圖示（分叉的線條圖）
2. 看到目前沒有待 commit 的變更（因為剛 commit 完）

📸 截圖 F1：VS Code Source Control 面板（標出 Source Control 圖示和空的 Changes 區域）

試著修改一個檔案再觀察變化：

echo "這是我的團隊專題" >> README.md

📸 截圖 F2：VS Code Source Control 出現變更（標出 Changes 底下的 README.md，以及差異預覽）

Step 19：用 Git Graph 看 commit 歷史

1. 在 Source Control 面板上方，找到 Git Graph 的圖示按鈕（或 Cmd+Shift+P → 搜尋 Git Graph）
2. 點開後看到 commit 歷史的視覺化樹狀圖

📸 截圖 G1：Git Graph 介面（標出 Git Graph 按鈕、commit 點、commit message）

目前只有一個 commit 點，看起來很簡單。等 EP02 學了 branch 和 merge 之後，這張圖會變得更豐富。

我們拿 GitHub 來做什麼？

• Git 是工具，負責版本控制
• GitHub 是平台，負責存放與協作、託管專案
• 你可以用 Git 但不用 GitHub（例如用 Git + GitLab / Bitbucket）
• GitHub 離不開 Git，因為它是基於 Git 架構的

用 Git + GitHub 管理專案

local vs. remote

• Git 裡的「遠端版本庫」位置，通常是存在 GitHub、GitLab 這類雲端服務上的一個專案。
• remote 就像你雲端硬碟上的專案資料夾，你本地只是其中一份副本。
• 你本地的專案（local repo）可以連接一個或多個 remote，這樣就能 push/pull 同步程式碼。
• origin 是 remote 的預設名稱
  • 當你用 git clone 下載一個專案時，Git 會自動把那個遠端取名為 origin。
  • 方便你不用記一長串網址，只要用 origin 這個別名就能操作。

上傳到 GitHub

git branch -M main

git push origin main

git push origin main -f

指令	功能
git branch -M main	把當前分支重新命名為 main（GitHub 預設主分支名）
git push origin main	把本地的 main 分支推到遠端（GitHub）
git push origin main -f	強制推送（⚠️ 會覆蓋遠端，只在確定要覆蓋時用）

Initialize repo & Publish to GitHub（用 VS Code GUI）

在 VS Code 裡可以完全用按鈕操作，不用打指令：

1. 打開 Source Control 面板（左側分叉線條圖示）
2. 點「Initialize Repository」按鈕 → 等同 git init
3. 寫好 code 後，在 Source Control 裡 stage + commit
4. 點「Publish Branch」按鈕 → VS Code 會自動幫你建 GitHub repo 並 push
5. 第一次會跳出 GitHub 登入頁面 → 「Sign in to GitHub to continue to Visual Studio Code」→ 登入授權

📸 截圖 G3：VS Code Initialize Repository → Publish Branch → GitHub 登入 三步流程

在 VS Code 建立新專案，上傳 GitHub 的步驟

1. 在 GitHub 建立空白 Repo（不要勾 README、.gitignore）

2. 在本機開啟 Terminal 並進入專案資料夾：

cd /path/to/project
git init

3. 加入檔案並提交：

git add .
git commit -m "initial commit"

4. 設定主分支與遠端：

git branch -M main
git remote add origin <repo-url>

5. 推送並建立追蹤：

git push -u origin main

💡 <repo-url> 在 GitHub 建完 Repo 後的 Quick setup 頁面可以複製（選 HTTPS）。

git clone：從 GitHub 複製專案到本機

git clone 是把 GitHub 上已經存在的專案完整下載到你的電腦。

git clone https://github.com/DataEngCamp/test

執行後會在目前資料夾下建立一個 test/ 資料夾，裡面就是完整的專案。

cd test
ls

✅ 預期：看到專案裡的檔案（例如 hahow_crawler.py、ptt_crawler.py 等）

💡 git clone vs git init 的差別：

• git clone：下載別人已有的專案
• git init：在本機建立全新的 Git 專案

Git config

查看 Git config

git config --list

設定你 Git config 的 user.name & user.email

# local（只對當前專案生效）
git config --local user.name "你的GitHub顯示名稱"
git config --local user.email "你的GitHub已驗證Email"

# global（對所有專案生效）
git config --global user.name "你的GitHub顯示名稱"
git config --global user.email "你的GitHub已驗證Email"

--local 只對當前 repo 生效，--global 對所有 repo 生效。建議先設 global，特殊專案再用 local 覆蓋。

常用 Git 指令

指令	功能
git init	在目前資料夾建立一個新的 Git 版本庫
git clone	從遠端版本庫複製一份完整的專案到本地
git add	將變更的檔案加入暫存區（準備提交）
git pull	抓取遠端更新並合併到當前本地分支
git commit	將暫存區的變更保存為一個版本
git fetch	抓取遠端更新但不自動合併，讓你先檢查差異
git push	把本地版本庫的更新上傳到遠端版本庫
git checkout	切換到指定分支或版本（也可用來建立新分支）
git diff	顯示檔案的差異（尚未提交或暫存的修改）
git merge	將其他分支的更新合併到當前分支

---

.gitignore

有些檔案我不想要上傳到 GitHub：

• 例如：CSV 檔、環境變數檔、VS Code 設定檔、Log 檔、金鑰
• 建立 .gitignore 將特定檔案/路徑忽略
  • 直接指定檔案：settings.json
  • 指定副檔名：*.log、*.csv
  • 指定資料夾：downloads/、venv/

總結

• WSL 讓你可以在 Windows 電腦裡執行 Linux (Ubuntu)
• 工程師必學 Linux，Linux 是業界開發和部署的首選環境
• VS Code 是工程師的利器，圖形化介面和良好的套件整合，讓開發更有效率
• Git/GitHub 寫程式的基礎，幫助個人和團隊管理程式碼

今天所學的內容，都是未來每次上課要用的，所以有問題務必排除！

---

12. 常見錯誤 & 排錯

#	錯誤	原因	解法
1	wsl --install 報「請啟用虛擬機器平台」	BIOS 的虛擬化沒開	重開機進 BIOS，啟用 Intel VT-x 或 AMD-V
2	WSL 裝完沒彈出 Ubuntu	需要重開機	重新開機
3	密碼打不出來	Linux 密碼不顯示	正常行為，照打就好
4	code . 沒反應	VS Code 沒裝或沒加入 PATH	重裝 VS Code，勾 Add to PATH
5	code . 開了但左下角沒有 WSL	沒裝 WSL extension	在 VS Code Extensions 搜尋 WSL，裝 Microsoft 的
6	python3: command not found	Ubuntu 沒有 Python	sudo apt install python3 -y
7	Mac brew: command not found	沒裝 Homebrew	跑 Homebrew 安裝指令
8	Permission denied	沒用 sudo	指令前加 sudo
9	VS Code Server 下載卡住	網路問題	等一下或換網路重試
10	WSL 跑很慢	可能是 WSL1 不是 WSL2	wsl --set-default-version 2
11	VS Code Server for WSL closed unexpectedly	VS Code Server 安裝損壞或 WSL 異常	見下方完整解法

「VS Code Server for WSL closed unexpectedly」完整解法

這個錯誤代表 VS Code 嘗試連線到 WSL 裡的 Server，但 Server 啟動失敗或意外關閉。

Step 1：先重啟 WSL

打開 PowerShell（不用系統管理員），輸入：

wsl --shutdown

等 5 秒。WSL 關閉後不需要特別「重開」，只要重新打開 Ubuntu 就會自動啟動：

• 從「開始」搜尋 Ubuntu 22.04 點開
• 或在 PowerShell 輸入 wsl
• 或在 VS Code 裡重新 code .（會自動啟動 WSL + 連線）

重新打開後，試一次 code .。

Step 2：如果還是不行，刪掉 VS Code Server 重裝

在 WSL Ubuntu 的 terminal 裡（不是 PowerShell）輸入：

rm -rf ~/.vscode-server

這會刪掉 WSL 裡的 VS Code Server。下次 code . 時 VS Code 會自動重新下載安裝。

Step 3：如果還是不行，更新 WSL 核心

回到 PowerShell：

wsl --update
wsl --shutdown

更新完重開 VS Code。

Step 4：確認 VS Code 和 WSL Extension 是最新版

• VS Code：左下角齒輪 → Check for Updates
• WSL Extension：Extensions 面板搜尋 WSL → 確認沒有 Update 按鈕

Step 5：如果以上都不行

在 WSL terminal 裡查看錯誤 log：

cat ~/.vscode-server/data/logs/*/remoteagent.log | tail -20

把 log 內容截圖，交給老師或 TA 看。

---

13. 指令速查表

指令	功能	範例
pwd	你在哪	pwd → /home/dex
ls	看有什麼	ls -la
cd	切換目錄	cd projects
cd ..	回上一層	cd ..
cd ~	回家目錄	cd ~
mkdir	建資料夾	mkdir myapp
touch	建空檔案	touch app.py
cat	看檔案內容	cat hello.txt
echo	輸出文字	echo "hi" > file.txt
cp	複製	cp a.txt b.txt
mv	移動/改名	mv old.txt new.txt
rm	刪除	rm file.txt
rm -r	刪資料夾	rm -r folder/
sudo	管理員權限	sudo apt install xxx
code .	用 VS Code 開	code .

---