生活分享

settings.json:全域、專案與環境變數

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

更新日期: 閱讀時間約 4 分鐘

LINE 分享
設定與指示檔的分工的原創插畫,以文件、裝置與流程等物件呼應全域、專案與環境變數;非產品介面。
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 開始前:找出真正使用的設定
  2. 2. 先理解:JSON 結構與設定優先順序
  3. 3. 實作:用最小設定確認作用
  4. 4. 環境變數:分開設定與秘密
  5. 5. 常見問題與回復方式
  6. 6. 完成後的檢核

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

settings.json:程式設定與選項;GEMINI.md:提供工作指示;環境變數:另外管理執行環境
設定與指示檔的分工。此為原創教學圖解,並非產品畫面或實測輸出。 · 圖片:Mokaair (© Mokaair)

開始前:找出真正使用的設定

使用者設定通常位於家目錄的 .gemini/settings.json;專案設定位於專案根目錄的 .gemini/settings.json。兩個檔案名稱相同,但適用範圍不同。在 Windows 開啟檔案前先確認完整路徑,避免在下載資料夾或另一個專案中改了同名檔案。

如果檔案已存在,先備份並閱讀內容。公司管理的環境可能另有系統預設或強制設定,無法由個人設定自由改動。這種情況應詢問管理員目前的政策,不要以為刪除專案設定就會移除系統限制。練習時從自己擁有的測試專案開始,降低判讀範圍。

先理解:JSON 結構與設定優先順序

JSON 的鍵與文字值使用雙引號,物件用大括號包住,陣列用中括號。最後一個專案後不要多放逗號,也不要把教學中的註解直接貼成 JSON。很多「設定沒生效」其實是語法錯誤;先讓檔案可被解析,才有辦法討論設定值是否受支援。

官方文件列出預設值、系統預設、使用者、專案與系統強制設定等來源,環境變數與啟動引數也可能影響結果。記住「我在這份檔案寫了什麼」不等於「目前實際值就是什麼」。要同時檢視啟動命令、環境與互動設定,才能追查覆寫來源。

實作:用最小設定確認作用

  1. 在測試專案建立 .gemini 資料夾;如果已有設定檔,先另存備份,不要整份覆蓋。
  2. 用下面範例指定上下檔名。此範例仍使用標準 GEMINI.md,目的在確認結構與放置位置。
  3. 儲存為 UTF-8,使用支援 JSON 的編輯器檢查括號、引號與逗號。
  4. 從專案根目錄重新啟動 CLI,開啟 /settings 檢查可見設定,再用 /memory list 核對規則載入。
  5. 如果要加入另一個指示檔名,先建立那份檔案,再將名稱加入陣列,重新啟動並核對 show 結果。
.gemini/settings.json · json
{
  "context": {
    "fileName": ["GEMINI.md"]
  }
}

上面只示範一個設定區塊。既有檔案如果還有 mcpServers、hooks 或其他內容,應把 context 合併進原本物件,而不是刪掉其他鍵。編輯前後使用差異比較,確認只有你預期的欄位改變。各功能的設定值要回到對應教學查詢,不要把別的版本截圖照抄進來。

環境變數:分開設定與秘密

某些連線設定可以引用環境變數,讓公開設定只記錄變數名稱。這與直接把金鑰貼進 JSON 不同;但也不代表任何環境變數都會自動被 CLI 視為認證。認證所需名稱與登入方式,請依確認。

PowerShell:僅示範一般變數 · powershell
$env:EDITORIAL_PROJECT = "announcement-demo"
Write-Output $env:EDITORIAL_PROJECT

這個示範變數不是 Gemini API 金鑰,也不會替你登入。它只展示目前 PowerShell 工作階段如何設定值;關閉視窗後的行為與系統永久環境設定不同。真實金鑰請依使用的認證流程設定,分享錯誤記錄時只顯示「是否存在」,不要印出值。

常見問題與回復方式

如果電腦有 Python,可以先用內建 JSON 工具檢查語法。從專案根目錄執行下面命令;成功時會印出格式化內容,失敗時會指出行列位置。這只證明 JSON 格式正確,不會替你檢查 Gemini 是否支援每個鍵。真實設定含秘密時不要把整段輸出分享出去,教學練習請只使用上面的最小內容。

檢查練習設定的 JSON 語法 · bash
python -m json.tool .gemini/settings.json

測試前也記錄你用來啟動 CLI 的命令。如果命令列指定了不同模型或其他引數,檔案中的設定可能不是最後生效的值。先用最單純的 gemini 啟動,再逐個加入引數比對,通常比同時修改全域與專案兩份檔案更容易找出原因。

「CLI 回報無法解析設定」先用 JSON 編輯器定位行號。全形引號、尾端逗號與貼入程式碼圍欄都是常見原因。修好語法後重新啟動;若仍有問題,還原備份,再一次只加入一個設定,逐步縮小出錯範圍。

「/settings 找不到某個專案」可能是版本差異、該專案只能從檔案設定,或教學對應的功能尚未提供。先記下 /about 的版本,再查同版本的官方參考。不要因為介面沒有欄位,就改寫未知鍵並假設它會生效。

「換資料夾後行為改變」要檢查新的專案設定與信任狀態。全域偏好不需要複製到每個專案;專案限定設定也不應留在家目錄影響所有工作。完成後可以接著設定,但先保留這份能正常啟動的最小基準,讓後續問題容易回復與比較。

完成後的檢核

完成實作後逐項確認。
檢查項目通過條件
操作能依正文重做一次,說明每一步使用的輸入。
結果能用原始資料或可重現測試核對輸出,而非只看語氣。
延伸知道下一篇教學解決的問題,以及什麼時候需要它。

接著可以閱讀 、,把本篇的操作接到下一個工作流程。

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享
  • 生活分享

    完整實作:文件摘要與資料擷取工具

    這篇把前面學過的提示詞、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 的操作直接套程式式。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享