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

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

圖:本站根據 LangGraph CLI 官方排錯文檔 整理的示意圖
三、啟動前必查的四條避坑清單
- 刪掉手寫的
checkpointer:自己單跑腳本測試時我們常寫builder.compile(checkpointer=InMemorySaver()),但切到langgraph dev前請改回無參的builder.compile()(或把儲存器留在if __name__ == "__main__":塊裏),讓服務端接管線程持久化與時間旅行快照; .env絕不進版本庫:langgraph.json本身只包含相對路徑映射,應該提交進 Git 供全組共用;而"env": ".env"指向的密鑰文件必須寫進.gitignore,團隊可另外提交一份空的.env.example作為模板;- 跨目錄導入用標準包名:當
"dependencies": ["."]把src安裝為可編輯包後,agent.py引用同倉庫工具模組時請用規範的包絕對導入或顯式相對導入,避免直接裸寫依賴啟動目錄位置的導入路徑; - 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 直接把本地源碼目錄加入搜尋路徑並安裝指定包。
相關教學
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安裝與第一個狀態圖
- /guides/langgraph-debug-visualize-studio-guide:用
langgraph dev啟動 Studio 可視化調試 - /guides/langgraph-pricing-open-source-vs-platform:LangGraph 開源自建與商業平台計費說明
- /guides/langgraph-mcp-integration-guide:LangGraph 異步接入 MCP 工具伺服器
參考資料
- LangChain / LangGraph 官方文檔:CLI & Configuration file reference — https://docs.langchain.com/
langchain-ai/langgraph官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph
0 條評論
還沒有評論,來搶沙發~