---
# System prepended metadata

title: 在 Windows 11 WSL 中安裝與設定 Gemini CLI 指南
tags: [WSL, Gemini CLI, Windows11]

---

# 在 Windows 11 WSL 中安裝與設定 Gemini CLI 指南

這是一份詳細的指南，將引導你如何在 Windows 11 的 WSL (Windows Subsystem for Linux) 環境中，從零開始安裝、設定並成功運行 Google Gemini CLI。[Gemini Cli](https://github.com/google-gemini/gemini-cli)
## 先決條件

-   你已經在 Windows 11 中安裝並設定好 WSL2。
-   你擁有一個可以正常運作的 WSL 發行版 (例如 Ubuntu)。

---

## 步驟一：安裝 Node.js (使用 NVM)

Gemini CLI 是基於 Node.js 開發的，因此我們需要先安裝它。使用 `nvm` (Node Version Manager) 是管理 Node.js 版本的推薦方式。

1.  **下載並安裝 nvm**：
    在你的 WSL 終端機中執行以下指令。

    ```bash
    # 下載並執行 nvm 安裝腳本
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    ```

2.  **載入 nvm 指令**：
    為了立即使用 nvm 而非重啟終端機，請執行：

    ```bash
    # 讓 nvm 指令在當前的 shell 生效
    \. "$HOME/.nvm/nvm.sh"
    ```

3.  **下載並安裝 Node.js**：
    使用 nvm 安裝指定的 Node.js 版本 (此處為 v22)。

    ```bash
    # 安裝 Node.js 22 版
    nvm install 22
    ```

4.  **驗證安裝**：
    檢查 Node.js 和 npm 的版本以確認安裝成功。

    ```bash
    # 驗證 Node.js 版本
    node -v
    nvm current

    # 驗證 npm 版本
    npm -v
    ```

---

## 步驟二：安裝 Gemini CLI

現在 Node.js 環境已經就緒，你可以使用 `npm` 來全域安裝 Gemini CLI。

1.  在你的 WSL 終端機中，執行以下指令：

    ```bash
    npm install -g @google/gemini-cli
    ```
    > `-g` 旗標代表「全域 (global)」，讓你可以在系統的任何路徑下執行 `gemini` 指令。

2.  安裝完成後，可以執行 `gemini --version` 來確認是否安裝成功。

---

## 步驟三：獲取 Google AI Studio API 金鑰(如果要使用賬號登錄可跳過步驟三和步驟四)

在啟動 Gemini CLI 之前，你需要一組 API 金鑰來進行身分驗證。

1.  **前往 Google AI Studio**：
    點擊此連結 [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)。

2.  **登入你的 Google 帳號**。

3.  **創建 API 金鑰**：
    點擊 **"Create API key in new project"** 按鈕。

4.  **複製金鑰**：
    系統會產生一組獨一無二的 API 金鑰。請立即將它複製下來，並存放在安全的地方。**這組金鑰只會完整顯示這一次，請務必妥善保管，不要洩漏給他人。**

---

## 步驟四：設定 API 金鑰環境變數

為了讓 Gemini CLI 能夠讀取到你的 API 金鑰，最推薦的方式是將它儲存在一個 `.env` 檔案中。

1.  **在你的 WSL 家目錄中建立 `.env` 檔案**：
    打開你的 WSL 終端機，執行以下指令。請將 `YOUR_API_KEY_HERE` 替換為你在上一步複製的真實金鑰。

    ```bash
    echo "GOOGLE_API_KEY=YOUR_API_KEY_HERE" > ~/.env
    ```
    > **為什麼用這個方法？**
    > -   直接在 WSL 中建立檔案可以避免 Windows 和 Linux 之間因換行符不同 (CRLF vs LF) 而產生的問題。
    > -   `~` 代表你的 WSL 家目錄 (例如 `/home/username`)，將設定檔放在這裡是很好的實踐。

2.  **移動到家目錄**：
    為了方便下一步啟動，請確保你在含有 `.env` 檔案的目錄下。

    ```bash
    cd ~
    ```

---

## 步驟五：啟動並使用 Gemini CLI

一切準備就緒！現在可以啟動 Gemini CLI 並開始互動了。

1.  **啟動互動模式 (Chat)**：
    在你的 WSL 終端機中 (請確保你位於含有 `.env` 檔案的目錄下)，直接輸入：

    ```bash
    gemini
    ```
    成功啟動後，你會看到一個 `>>>` 提示符，可以開始連續對話。

2.  **單次查詢 (Generate)**：
    如果你只想快速得到一次性回覆，可以直接將問題作為參數傳遞：
    ```bash
    gemini "請給我一段關於如何學習程式設計的建議"
    ```

---

## 附錄：常用 Gemini CLI 指令範例

以下是一些實用的指令範例，展示 Gemini CLI 的強大功能。

### 1. 程式碼相關

-   **解釋程式碼**：
    將程式碼檔案的內容透過管道 (pipe) 傳送給 Gemini 進行分析。
    ```bash
    cat main.py | gemini "請解釋這段 Python 程式碼的功能"
    ```

-   **產生程式碼草稿**：
    根據需求描述，產生一個新功能的初步程式碼。
    ```bash
    gemini "用 Go 語言寫一個函式，用來計算檔案的 SHA256 hash" > filehasher.go
    ```

-   **重構或遷移程式碼**：
    ```bash
    gemini "幫我將這個專案從使用舊版的 API 遷移到 v2 版本，請先提供一個計畫"
    ```

### 2. 檔案與系統操作

-   **總結文件內容**：
    ```bash
    cat report.pdf | gemini "請總結這份報告的重點"
    ```

-   **多模態查詢 (分析圖片)**：
    Gemini CLI 支援分析圖片內容。
    ```bash
    gemini "這張圖片裡有什麼？" diagram.png
    ```
    ```bash
    gemini "請根據這張線框圖 (wireframe) 產生對應的 HTML 結構" wireframe.jpg
    ```

-   **自動化腳本**：
    讓 Gemini 幫你編寫 shell 指令來完成任務。
    ```bash
    gemini "寫一個 shell 指令，將這個目錄下所有的 .jpg 圖片轉換為 .png 格式"
    ```

### 3. 結合其他工具

-   **分析 Git 歷史紀錄**：
    結合 `git` 指令，讓 Gemini 幫你整理版本歷史。
    ```bash
    git log --since="1 week ago" | gemini "請將這週的 git 提交紀錄，按照功能和作者進行分組總結"
    ```

-   **產生簡報**：
    ```bash
    gemini "為過去7天的 git 歷史紀錄做一個簡報，按功能和團隊成員分組"
    ```

---

## 附錄二：卸載與更新 Gemini CLI

你的卸載方法取決於你當初如何執行 CLI。請根據你是使用 `npx` 或是全域安裝 (`npm install -g`) 來選擇對應的指示。

### 卸載

如果你是透過全域方式安裝 CLI (例如 `npm install -g @google/gemini-cli`)，請使用 `npm uninstall` 指令並加上 `-g` 旗標來移除它。

```bash
npm uninstall -g @google/gemini-cli
```

這個指令會將該套件從你的系統中完整移除。
### 更新

如果你是透過全域方式安裝 CLI (例如 `npm install -g @google/gemini-cli`)，請使用 `npm install` 指令並加上 `-g` 旗標來更新它。

```bash
npm install -g @google/gemini-cli
```