langgraph.json 配置文件詳解:字段說明、目錄結構與常見啟動報錯排查

用 langgraph dev 啟動 Studio 調試或用 langgraph build 打包時,項目根目錄必須有 langgraph.json。本文按官方 CLI 規範講清 dependencies、graphs、env 等核心字段寫法與排錯要點。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 先明確什麼時候需要它:只有當你使用官方命令行工具(langgraph dev、langgraph up、langgraph build)或託管平台時才需要 langgraph.json;如果你只是自己寫 python app.py 或用自有 FastAPI 包裝開源庫(見 /guides/langgraph-pricing-open-source-vs-platform),完全不需要這個文件。
  2. 最小可用配置只需三個鍵:dependencies(裝哪些包)、graphs(圖變量在哪)、env(環境變量文件在哪)。
  3. graphs 的值格式嚴格為 "相對文件路徑:變量名或工廠函數名",所有相對路徑均以 langgraph.json 所在目錄為基準解析。
  4. 頭號避坑點:寫進 graphs 暴露給 CLI 伺服器的圖,在 builder.compile() 時不要手動傳入 InMemorySaver 等自定義檢查點,服務端會自動注入統一的持久化存儲,手動傳反而會衝突報錯。

langgraph.json 核心配置字段一覽

圖:本站根據 LangGraph CLI 配置文件官方文檔 整理的示意圖

本文根據 LangChain / LangGraph CLI 官方配置文件參考文檔整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。

適用於誰

  • 搜「langgraph json 配置」「langgraph.json 怎麼寫」的人;
  • 想運行 langgraph dev 打開可視化面板(用法見 /guides/langgraph-debug-visualize-studio-guide),結果一敲命令就報缺少配置文件或找不到圖變量的開發者;
  • 需要在一份服務裏同時暴露多個不同業務狀態圖、或者自定義系統級依賴與鑑權鉤子的後端工程師。

一、標準項目目錄結構與最小模板

新手配 langgraph.json 最容易卡在「寫了 "dependencies": ["."] 卻報本地包無法安裝」。原因是 "." 代表把當前根目錄當成一個標準 Python 項目來解析依賴,因此根目錄下應當配套放好 pyproject.toml(或直接在 dependencies 裏引用包名與 requirements.txt 所在目錄)。

推薦的乾淨目錄結構如下:

text
my-langgraph-app/
├── .env                  # 存放 API Key(務必加入 .gitignore)
├── langgraph.json        # CLI 核心配置文件
├── pyproject.toml        # 聲明 langgraph、langchain-openai 等依賴
└── src/
    └── agent.py          # 定義並導出 graph = builder.compile()

對應的最小 langgraph.json 只需寥寥幾行(agent.py 內部的狀態圖寫法見 /guides/langgraph-quickstart-install-first-graph):

json
{
  "dependencies": ["."],
  "graphs": {
    "support_bot": "./src/agent.py:graph",
    "code_helper": "./src/coder.py:coder_graph"
  },
  "env": ".env"
}

這裏 "graphs" 可以登記多張不同的圖:左邊鍵名(如 "support_bot")是你在 Studio 下拉框或 HTTP 接口裏看到的助手 ID,右邊冒號前是源碼路徑,冒號後是文件頂層導出的變量名。

二、進階字段示例:Python 版本、容器指令與異步圖工廠

當你的項目需要接外部 MCP 服務(見 /guides/langgraph-mcp-integration-guide)、指定固定 Python 版本打包鏡像、或者在系統容器裏補裝底層 C 庫(例如編譯驅動或字體包)時,可以擴展使用下面的完整字段:

json
{
  "python_version": "3.12",
  "dependencies": ["."],
  "graphs": {
    "mcp_agent": "./src/mcp_graph.py:make_graph"
  },
  "env": ".env",
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*"
  ],
  "auth": {
    "path": "./src/security.py:auth"
  }
}

裏面有兩個非常實用的工程技巧:

  1. 冒號後面不僅可以寫編譯好的變量,還可以寫「無參或接收配置的圖構造函數」(如上例的 :make_graph):當你的圖在初始化階段必須先異步拉取遠程 MCP 工具列表時,無法在模組頂層直接同步寫死 graph = ...,寫成 async def make_graph(): ... return builder.compile() 交給服務端按需異步構建即可;
  2. dockerfile_lines 只在使用 Docker 構建命令(langgraph build / langgraph up)時生效:如果你平時只跑純內存熱重載的 langgraph dev,CLI 直接複用你當前的本地虛擬環境,不會執行 Docker 指令。

langgraph.json 常見啟動報錯排查

圖:本站根據 LangGraph CLI 官方排錯文檔 整理的示意圖

三、啟動前必查的四條避坑清單

  1. 刪掉手寫的 checkpointer:自己單跑腳本測試時我們常寫 builder.compile(checkpointer=InMemorySaver()),但切到 langgraph dev 前請改回無參的 builder.compile()(或把儲存器留在 if __name__ == "__main__": 塊裏),讓服務端接管線程持久化與時間旅行快照;
  2. .env 絕不進版本庫:langgraph.json 本身只包含相對路徑映射,應該提交進 Git 供全組共用;而 "env": ".env" 指向的密鑰文件必須寫進 .gitignore,團隊可另外提交一份空的 .env.example 作為模板;
  3. 跨目錄導入用標準包名:當 "dependencies": ["."] 把 src 安裝為可編輯包後,agent.py 引用同倉庫工具模組時請用規範的包絕對導入或顯式相對導入,避免直接裸寫依賴啟動目錄位置的導入路徑;
  4. TypeScript 項目怎麼配:如果是 JS / TS 版 LangGraph,同樣叫 langgraph.json,只需把 python_version 換成 "node_version": "20",並確保根目錄存在聲明瞭依賴的 package.json 即可。

平時在本地結合大模型快速生成 pyproject.toml 與排查包版本鎖衝突時,如需核對個人官方 ChatGPT 訂閱方案,可參考 /chongzhi/chatgpt-plus 頁面說明。

常見問題

Q:配置文件不放在項目根目錄、放在子文件夾裏可以嗎?

可以,運行命令時加上 -c(或 --config)參數顯式指定路徑即可,例如 langgraph dev -c ./deploy/langgraph.json。但請記住文件內部寫的 ./src/agent.py 和 .env 依然會相對於 deploy/ 文件夾去尋找,放在倉庫根目錄最不容易搞錯層級。

Q:不想寫 pyproject.toml,只用 requirements.txt 怎麼填 dependencies?

如果暫時不想配 pyproject.toml,可以在項目目錄放好 requirements.txt,或直接在 dependencies 數組裏列出第三方包名(如 ["langchain_openai", "./src"]),讓 CLI 直接把本地源碼目錄加入搜尋路徑並安裝指定包。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔:CLI & Configuration file reference — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~