- 登入
- 註冊
Gemini CLI 部署
我的 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
。
- 安裝工具:打開 Mac 的獨立終端機,用
sudo
全域安裝 Gemini CLI。# 使用 sudo 解決 macOS 上的全域安裝權限問題 sudo npm install -g @google/gemini-cli
- 觸發登入:執行
gemini
,它會自動打開網頁瀏覽器。# 啟動 gemini 來觸發網頁授權流程 gemini
- 完成授權:在瀏覽器中,選擇您的 Google 帳號並點擊「允許」。
- 取得憑證:回到終端機,按
Control + C
退出。此時,真實的憑證檔案已經生成在~/.gemini/oauth_creds.json
。
步驟 2:建立並準備您的專案工作區
接下來,我們建立一個專門的資料夾來存放我們的專案檔案和憑證。
- 建立資料夾:在桌面上建立一個新資料夾。
💡 專業提示:資料夾名稱請使用英文,並且不要包含空格,例如
gemini-project
。這能避免未來在各種工具中遇到路徑問題。 - 複製憑證:將我們剛剛拿到的憑證,複製到這個新的專案資料夾裡。
# cp [來源] [目的地] # 將隱藏在家目錄的憑證檔,複製到我們的工作區 cp ~/.gemini/oauth_creds.json ~/Desktop/gemini-project/
步驟 3:建立並設定您的「開發專用」Docker 容器
這是最核心的一步!我們將啟動一個常駐的容器,並把所有設定一次性搞定。
- 進入工作區:在 Mac 終端機中,進入您的專案資料夾。
cd ~/Desktop/gemini-project
- 啟動常駐容器:執行以下指令,來啟動一個在背景運行的容器。
# -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
- 進入容器進行「裝修」:使用
docker exec
進入這個新啟動的容器。# exec: 進入一個正在運行的容器 # -it: 啟用互動模式 docker exec -it my-gemini-env bash
- 在容器內進行一次性設定:
# 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/
- 驗收:在容器內執行
gemini
,應該能直接進入>
互動模式。成功後,輸入exit
離開容器。
my-gemini-env
的、配置齊全的永久開發環境。第二部分:【日常開發】如何重複使用您的環境 🔄
從現在開始,您每天的工作流程將會變得非常簡單,再也不用重複安裝和設定了。
情境一:從 Mac 的獨立終端機進入
最直接的方式。
# 直接用 exec 進入您已經設定好的容器
docker exec -it my-gemini-env bash
進入後,所有工具和憑證都已就緒,可以直接使用 gemini
。工作結束後,輸入 exit
離開。
情境二:從 VS Code 的終端機進入(專業推薦!)
這是最高效的工作方式,可以實現程式碼編輯與終端機執行的無縫銜接。
- 用 VS Code 打開專案資料夾:打開 VS Code,選擇 `檔案` -> `打開資料夾…`,選擇桌面上的 `gemini-project`。
- 打開內建終端機:按下快捷鍵
Control
+~
。 - 進入開發容器:在 VS Code 的終端機面板裡,輸入完全相同的指令:
docker exec -it my-gemini-env bash
現在您就在 VS Code 的視窗裡,進入了您配置好的 Docker 開發環境。您可以一邊編輯 /workspace
裡的檔案(會同步回 Mac),一邊在終端機裡執行 gemini
指令。這就是專業的開發流程!
補充:如果電腦重開機了怎麼辦? 😴
Docker 容器預設不會隨電腦開機而啟動。如果您的 Mac 重開機了,只需兩步就能恢復環境:
- 啟動 Docker Desktop。
- 在終端機輸入以下指令來**重新啟動**您停止的容器:
docker start my-gemini-env
啟動後,您就可以像平常一樣,用 docker exec
進入它了,所有設定都還在!
希望這份詳細的筆記對您有幫助。Happy Coding! 🎉