生活分享
settings.json:全域、專案與環境變數
settings.json 管理 Gemini CLI 的程式設定;GEMINI.md 則提供專案指示。這篇帶你辨識全域與專案設定,編輯一個最小 JSON 範例,並用實際載入結果檢查是否生效。你也會學到如何處理環境變數,避免把金鑰直接寫進可分享的設定檔。
更新日期: 閱讀時間約 4 分鐘

settings.json 管理 Gemini CLI 的程式設定;GEMINI.md 則提供專案指示。這篇帶你辨識全域與專案設定,編輯一個最小 JSON 範例,並用實際載入結果檢查是否生效。你也會學到如何處理環境變數,避免把金鑰直接寫進可分享的設定檔。
開始前:找出真正使用的設定
使用者設定通常位於家目錄的 .gemini/settings.json;專案設定位於專案根目錄的 .gemini/settings.json。兩個檔案名稱相同,但適用範圍不同。在 Windows 開啟檔案前先確認完整路徑,避免在下載資料夾或另一個專案中改了同名檔案。
如果檔案已存在,先備份並閱讀內容。公司管理的環境可能另有系統預設或強制設定,無法由個人設定自由改動。這種情況應詢問管理員目前的政策,不要以為刪除專案設定就會移除系統限制。練習時從自己擁有的測試專案開始,降低判讀範圍。
先理解:JSON 結構與設定優先順序
JSON 的鍵與文字值使用雙引號,物件用大括號包住,陣列用中括號。最後一個專案後不要多放逗號,也不要把教學中的註解直接貼成 JSON。很多「設定沒生效」其實是語法錯誤;先讓檔案可被解析,才有辦法討論設定值是否受支援。
官方文件列出預設值、系統預設、使用者、專案與系統強制設定等來源,環境變數與啟動引數也可能影響結果。記住「我在這份檔案寫了什麼」不等於「目前實際值就是什麼」。要同時檢視啟動命令、環境與互動設定,才能追查覆寫來源。
實作:用最小設定確認作用
- 在測試專案建立 .gemini 資料夾;如果已有設定檔,先另存備份,不要整份覆蓋。
- 用下面範例指定上下檔名。此範例仍使用標準 GEMINI.md,目的在確認結構與放置位置。
- 儲存為 UTF-8,使用支援 JSON 的編輯器檢查括號、引號與逗號。
- 從專案根目錄重新啟動 CLI,開啟 /settings 檢查可見設定,再用 /memory list 核對規則載入。
- 如果要加入另一個指示檔名,先建立那份檔案,再將名稱加入陣列,重新啟動並核對 show 結果。
{
"context": {
"fileName": ["GEMINI.md"]
}
}
上面只示範一個設定區塊。既有檔案如果還有 mcpServers、hooks 或其他內容,應把 context 合併進原本物件,而不是刪掉其他鍵。編輯前後使用差異比較,確認只有你預期的欄位改變。各功能的設定值要回到對應教學查詢,不要把別的版本截圖照抄進來。
環境變數:分開設定與秘密
某些連線設定可以引用環境變數,讓公開設定只記錄變數名稱。這與直接把金鑰貼進 JSON 不同;但也不代表任何環境變數都會自動被 CLI 視為認證。認證所需名稱與登入方式,請依CLI 認證教學CLI 認證:Google 帳號、API Key 與計費Gemini CLI 的登入方式會影響可使用的服務、額度與計費歸屬。本篇帶你比較 Google 帳號登入、Gemini API Key 與 Vertex AI,完成適合自己的認證,並用最小對話驗證。重點是知道目前到底使用哪個帳號與專案,而不是只看到登入成功就假設所有功能都包含在訂閱裡。閱讀全文確認。
$env:EDITORIAL_PROJECT = "announcement-demo"
Write-Output $env:EDITORIAL_PROJECT
這個示範變數不是 Gemini API 金鑰,也不會替你登入。它只展示目前 PowerShell 工作階段如何設定值;關閉視窗後的行為與系統永久環境設定不同。真實金鑰請依使用的認證流程設定,分享錯誤記錄時只顯示「是否存在」,不要印出值。
常見問題與回復方式
如果電腦有 Python,可以先用內建 JSON 工具檢查語法。從專案根目錄執行下面命令;成功時會印出格式化內容,失敗時會指出行列位置。這只證明 JSON 格式正確,不會替你檢查 Gemini 是否支援每個鍵。真實設定含秘密時不要把整段輸出分享出去,教學練習請只使用上面的最小內容。
python -m json.tool .gemini/settings.json
測試前也記錄你用來啟動 CLI 的命令。如果命令列指定了不同模型或其他引數,檔案中的設定可能不是最後生效的值。先用最單純的 gemini 啟動,再逐個加入引數比對,通常比同時修改全域與專案兩份檔案更容易找出原因。
「CLI 回報無法解析設定」先用 JSON 編輯器定位行號。全形引號、尾端逗號與貼入程式碼圍欄都是常見原因。修好語法後重新啟動;若仍有問題,還原備份,再一次只加入一個設定,逐步縮小出錯範圍。
「/settings 找不到某個專案」可能是版本差異、該專案只能從檔案設定,或教學對應的功能尚未提供。先記下 /about 的版本,再查同版本的官方參考。不要因為介面沒有欄位,就改寫未知鍵並假設它會生效。
「換資料夾後行為改變」要檢查新的專案設定與信任狀態。全域偏好不需要複製到每個專案;專案限定設定也不應留在家目錄影響所有工作。完成後可以接著設定自訂指令自訂斜線指令:TOML、參數與重新載入自訂斜線指令可以把經常重複的提示詞存成 Gemini CLI 的快捷操作。例如每次整理公告都要保留日期、地點與缺漏資料,可以包成 /summary。本篇從不執行 shell 的純提示詞指令開始,教你建立 TOML、傳入引數、重新載入及檢查結果。閱讀全文,但先保留這份能正常啟動的最小基準,讓後續問題容易回復與比較。
完成後的檢核
| 檢查項目 | 通過條件 |
|---|---|
| 操作 | 能依正文重做一次,說明每一步使用的輸入。 |
| 結果 | 能用原始資料或可重現測試核對輸出,而非只看語氣。 |
| 延伸 | 知道下一篇教學解決的問題,以及什麼時候需要它。 |
接著可以閱讀 GEMINI.md 進階GEMINI.md 進階:範圍、匯入與 /memory同時使用多個專案時,GEMINI.md 不一定只有一份。Gemini CLI 可以從全域設定、工作目錄與相關子目錄取得指示,並合併成模型看到的上下文。本篇教你追查實際載入了哪些檔案、匯入共用規則,以及用可重現的測試確認更新是否生效。閱讀全文、CLI 權限CLI 權限:忽略檔案、可信任資料夾與沙箱Gemini CLI 能讀取檔案與呼叫工具,因此開始使用前,要理解忽略檔案、資料夾信任與沙箱各控制什麼。本篇在獨立練習專案中建立 .geminiignore,檢查資料夾信任選項,再辨識啟動沙箱所需條件。完成後,你能說明每一層的用途,而不會把文字規則當成檔案存取的完整隔離。閱讀全文,把本篇的操作接到下一個工作流程。
返回 Gemini 教學總目錄Gemini 完整教學:電腦、手機、CLI 與 Google AI 應用這裡整理 Gemini、Google AI 與開發工具的教學。可以按分類找功能、按自己的需求走學習路線,也可以搜尋「MD」「手機」「PDF」「/memory」等關鍵字。每篇都提供步驟、可複製範例、結果核對方式與延伸閱讀,不需要從第一篇一路讀到底。閱讀全文
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
完整實作:文件摘要與資料擷取工具
這篇把前面學過的提示詞、API 呼叫與 JSON 驗證串成一個可執行的檔案工具。輸入一份 UTF-8 活動公告,程式產生摘要、五個固定欄位、原文引用與待確認問題,再存成待審 JSON。你會練習把模型當作資料處理的一個步驟,讓驗證與儲存仍由程式明確控制。
生活分享
API 額度與錯誤:費用、重試與成本控制
Gemini API 的費用取決於模型、輸入輸出、服務模式及使用的工具;速率限制則決定你的專案在一段時間內能送出多少工作。本篇教你找到真正對應的用量頁面、估算一次檔案處理成本、分類錯誤,並設計有限重試與停止條件,避免把每個失敗都當成多按一次就能解決。
生活分享
API 檔案與 JSON:結構化輸出及驗證
Gemini API 可以讀取 PDF,再把結果整理成指定的 JSON 結構。本篇用虛構活動公告示範檔案輸入、欄位設計與本地驗證。學完後,你會知道「收到合法 JSON」與「內容確實來自檔案」是兩件需要分別檢查的事,並能保留缺漏資訊而不讓模型自行補齊。
生活分享
AI Studio 與第一個 Gemini API 呼叫
Google AI Studio 是試用模型與建立 Gemini API 金鑰的開發入口。本篇從一個簡單提示詞開始,帶你建立獨立專案環境,分別用 Python 與 JavaScript 呼叫 API。完成後,你會知道網頁試跑、程式執行與帳號用量各自在哪裡確認,不再把消費者版 Gemini 的操作直接套程式式。
引用本文的文章
資料來源
- Gemini CLI:設定參考查證日期:
- Gemini CLI:GEMINI.md 上下文查證日期:
本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。