结论先说
- 先明确什么时候需要它:只有当你使用官方命令行工具(
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 条评论
还没有评论,来抢沙发~