Gemini CLI 部署

我的 Gemini CLI on Docker (macOS) 學習之路:從零到一的終極SOP

我的 Gemini CLI on Docker (macOS) 學習之路:從零到一的終極SOP 🚀

大家好!最近在學習 Google 的 Gemini CLI,並嘗試在 Docker 環境中運行它。過程中遇到了許多經典的 Docker 新手問題,像是權限不足、找不到檔案、無法登入等等。經過一番摸索和除錯,我終於整理出了一套完整、高效的標準作業流程(SOP)。這份筆記記錄了從零開始,在 macOS 上配置一個可重複使用的 Gemini CLI Docker 開發環境的全過程,希望能幫助到同樣在學習路上的朋友們!

第一部分:【一次性設定】建立您的永久開發環境 (只需做一次!) 🏗️

這個階段的目標是建立一個常駐的、配置好的 Docker 容器,作為您未來專用的 Gemini 開發環境。我們把所有麻煩事都在這一步搞定!

步驟 1:在本機 (Mac) 取得 Google 登入憑證

首先,我們需要利用 Mac 強大的圖形介面和瀏覽器,來完成互動式登入,並取得最關鍵的憑證檔案 oauth_creds.json

  1. 安裝工具:打開 Mac 的獨立終端機,用 sudo 全域安裝 Gemini CLI。
    # 使用 sudo 解決 macOS 上的全域安裝權限問題
    sudo npm install -g @google/gemini-cli
  2. 觸發登入:執行 gemini,它會自動打開網頁瀏覽器。
    # 啟動 gemini 來觸發網頁授權流程
    gemini
  3. 完成授權:在瀏覽器中,選擇您的 Google 帳號並點擊「允許」。
  4. 取得憑證:回到終端機,按 Control + C 退出。此時,真實的憑證檔案已經生成在 ~/.gemini/oauth_creds.json

步驟 2:建立並準備您的專案工作區

接下來,我們建立一個專門的資料夾來存放我們的專案檔案和憑證。

  1. 建立資料夾:在桌面上建立一個新資料夾。
    💡 專業提示:資料夾名稱請使用英文,並且不要包含空格,例如 gemini-project。這能避免未來在各種工具中遇到路徑問題。
  2. 複製憑證:將我們剛剛拿到的憑證,複製到這個新的專案資料夾裡。
    # cp [來源] [目的地]
    # 將隱藏在家目錄的憑證檔,複製到我們的工作區
    cp ~/.gemini/oauth_creds.json ~/Desktop/gemini-project/

步驟 3:建立並設定您的「開發專用」Docker 容器

這是最核心的一步!我們將啟動一個常駐的容器,並把所有設定一次性搞定。

  1. 進入工作區:在 Mac 終端機中,進入您的專案資料夾。
    cd ~/Desktop/gemini-project
  2. 啟動常駐容器:執行以下指令,來啟動一個在背景運行的容器。
    # -d: 在背景運行 (detach)
    # --name: 給容器取一個好記的名字
    # -v: 掛載Volume,將本機資料夾同步到容器內 (volume mount)
    # tail -f /dev/null: 讓容器保持運行的技巧
    docker run -d --name my-gemini-env -v "$(pwd):/workspace" node:lts tail -f /dev/null
  3. 進入容器進行「裝修」:使用 docker exec 進入這個新啟動的容器。
    # exec: 進入一個正在運行的容器
    # -it: 啟用互動模式
    docker exec -it my-gemini-env bash
  4. 在容器內進行一次性設定
    # 1. 安裝 Gemini CLI 工具
    npm install -g @google/gemini-cli
    
    # 2. 建立 gemini 需要的設定檔目錄
    # -p: 如果父目錄不存在也一併建立
    mkdir -p /root/.gemini
    
    # 3. 從掛載的目錄 /workspace 複製憑證到正確位置
    cp /workspace/oauth_creds.json /root/.gemini/
  5. 驗收:在容器內執行 gemini,應該能直接進入 > 互動模式。成功後,輸入 exit 離開容器。
✅ 一次性設定到此全部完成!您現在擁有了一個叫做 my-gemini-env 的、配置齊全的永久開發環境。

第二部分:【日常開發】如何重複使用您的環境 🔄

從現在開始,您每天的工作流程將會變得非常簡單,再也不用重複安裝和設定了。

情境一:從 Mac 的獨立終端機進入

最直接的方式。

# 直接用 exec 進入您已經設定好的容器
docker exec -it my-gemini-env bash

進入後,所有工具和憑證都已就緒,可以直接使用 gemini。工作結束後,輸入 exit 離開。

情境二:從 VS Code 的終端機進入(專業推薦!)

這是最高效的工作方式,可以實現程式碼編輯與終端機執行的無縫銜接。

  1. 用 VS Code 打開專案資料夾:打開 VS Code,選擇 `檔案` -> `打開資料夾…`,選擇桌面上的 `gemini-project`。
  2. 打開內建終端機:按下快捷鍵 Control + ~
  3. 進入開發容器:在 VS Code 的終端機面板裡,輸入完全相同的指令:
    docker exec -it my-gemini-env bash

現在您就在 VS Code 的視窗裡,進入了您配置好的 Docker 開發環境。您可以一邊編輯 /workspace 裡的檔案(會同步回 Mac),一邊在終端機裡執行 gemini 指令。這就是專業的開發流程!

補充:如果電腦重開機了怎麼辦? 😴

Docker 容器預設不會隨電腦開機而啟動。如果您的 Mac 重開機了,只需兩步就能恢復環境:

  1. 啟動 Docker Desktop
  2. 在終端機輸入以下指令來**重新啟動**您停止的容器:
    docker start my-gemini-env

啟動後,您就可以像平常一樣,用 docker exec 進入它了,所有設定都還在!


希望這份詳細的筆記對您有幫助。Happy Coding! 🎉

我想訂閱電子報