使用 langgraph CLI 脚手架、开发、构建…

当你需要创建、本地开发、Docker 构建/运行、部署或管理 LangGraph 应用及 LangSmith Deployments 时使用。

适用场景

解决思路

1. langgraph CLI 管理 LangGraph 应用全生命周期：从脚手架新项目到部署到 LangGraph Platform（LangSmith Deployments）。关键命令包括 langgraph new、langgraph dev、langgraph build、langgraph up、langgraph deploy、langgraph dockerfile。
2. 除 new 外，所有命令都读取项目根目录的 langgraph.json 配置文件。
3. 安装 Python 完整版：pip install 'langgraph-cli[inmem]'，包含 langgraph dev 支持。
4. 安装 Python 精简版：pip install langgraph-cli，不带 dev server，仅支持 build/up/deploy。
5. 使用 UV 安装完整版：uv add 'langgraph-cli[inmem]'，包含 langgraph dev 支持。
6. 使用 UV 安装精简版：uv add langgraph-cli，不带 dev server，仅支持 build/up/deploy。
7. 使用 JavaScript CLI 按需运行：npx @langchain/langgraph-cli。
8. 全局安装 JavaScript CLI：npm install -g @langchain/langgraph-cli，之后命令为 langgraphjs。
9. 脚手架项目：langgraph new 进行交互式模板选择。
10. 在指定目录创建项目：langgraph new ./my-agent。
11. 跳过提示直接使用模板：langgraph new --template agent-python。
12. 可用模板包括：deep-agent-python、deep-agent-js、agent-python、new-langgraph-project-python、new-langgraph-project-js。
13. 本地开发：langgraph dev 默认运行在 localhost:2024，支持热重载且无需 Docker。
14. 自定义 dev 端口：langgraph dev --port 8000。
15. 指定 dev 配置路径：langgraph dev --config ./langgraph.json。
16. 禁用 dev 热重载：langgraph dev --no-reload。
17. 不自动打开 LangGraph Studio：langgraph dev --no-browser。
18. 绑定所有接口：langgraph dev --host 0.0.0.0，仅限可信网络。
19. 通过 Cloudflare tunnel 暴露远程访问：langgraph dev --tunnel。
20. 启用远程调试器：langgraph dev --debug-port 5678，需要 debugpy。
21. 设置每个 worker 最大并发作业数：langgraph dev --n-jobs-per-worker 20，默认 10。
22. 构建 Docker 镜像：langgraph build -t my-image，必须为镜像打 tag。
23. 构建时使用本地构建的基础镜像：langgraph build -t my-image --no-pull。
24. 构建时指定配置：langgraph build -t my-image -c langgraph.json。
25. 固定基础镜像版本：langgraph build -t my-image --base-image langchain/langgraph-server:0.2.18。
26. 通过 Docker Compose 启动 LangGraph API server：langgraph up，默认端口 8123，包含 Postgres。
27. 自定义 up 端口：langgraph up --port 8000。
28. up 时监听文件变化并重启：langgraph up --watch。
29. up 时强制全新构建：langgraph up --recreate，适合部署前验证。
30. 使用外部 Postgres：langgraph up --postgres-uri postgresql://...。
31. up 时使用本地镜像：langgraph up --no-pull，在 langgraph build 之后使用。
32. up 时跳过构建并使用预构建镜像：langgraph up --image my-image。
33. 添加额外 Docker 服务：langgraph up -d docker-compose.yml。
34. 提供调试器 UI：langgraph up --debugger-port 8124。
35. 阻塞直到服务健康：langgraph up --wait。
36. 部署到 LangGraph Platform（LangSmith Deployments）：langgraph deploy，名称默认为目录名。
37. 指定部署名称：langgraph deploy --name my-agent。
38. 生产部署：langgraph deploy --deployment-type prod，默认 dev。
39. 自定义镜像 tag：langgraph deploy --tag v1.2.0，默认 latest。
40. 按 ID 更新已有部署：langgraph deploy --deployment-id <id>。
41. 指定部署配置路径：langgraph deploy --config ./langgraph.json。
42. 不等待部署状态：langgraph deploy --no-wait。
43. 显示详细服务器日志：langgraph deploy --verbose。
44. 部署前置：在环境或 .env 中设置 LANGSMITH_API_KEY。
45. langgraph deploy 也接受构建 flags：--base-image、--pull/--no-pull。
46. 列出所有部署：langgraph deploy list。
47. 按名称过滤部署：langgraph deploy list --name-contains bot。
48. 删除部署：langgraph deploy delete <deployment-id>，交互确认。
49. 强制删除部署：langgraph deploy delete <deployment-id> --force，跳过确认。
50. 查看运行时日志：langgraph deploy logs，默认最后 100 条。
51. 按部署名称查看日志：langgraph deploy logs --name my-agent。
52. 按部署 ID 查看日志：langgraph deploy logs --deployment-id <id>。
53. 查看构建日志：langgraph deploy logs --type build。
54. 跟随或流式查看日志：langgraph deploy logs -f。
55. 按级别过滤日志：langgraph deploy logs --level error，可选 debug|info|warning|error|critical。
56. 搜索过滤日志：langgraph deploy logs -q timeout。
57. 增加日志条目数：langgraph deploy logs --limit 500。
58. 按时间范围查看日志：langgraph deploy logs --start-time 2026-03-08T00:00:00Z。
59. 生成 Dockerfile：langgraph dockerfile ./Dockerfile。
60. 同时生成 compose 等文件：langgraph dockerfile ./Dockerfile --add-docker-compose，生成 compose + .env + .dockerignore。
61. langgraph.json 是所有 CLI 命令（dev、build、up、deploy）使用的配置文件，默认位于当前目录 langgraph.json。
62. 最小 Python 配置：dependencies 为点号字符串，graphs 中 agent 指向 ./my_agent/agent.py:graph，env 指向 ./.env。
63. 最小 JavaScript 配置：dependencies 为点号字符串，graphs 中 agent 指向 ./src/agent.js:graph，env 指向 ./.env。
64. 完整配置示例包含：dependencies 包含点号、langchain_openai、./local_package；graphs 包含 agent 与 retriever；env 为 ./.env；python_version 为 3.12；pip_config_file 为 ./pip.conf；dockerfile_lines 包含 RUN apt-get update && apt-get install -y ffmpeg。
65. dependencies 键必需：依赖数组。点号表示通过 pyproject.toml、setup.py、requirements.txt 或 package.json 查找本地包；也可以是子目录路径（如 ./my_pkg）或包名（如 langchain_openai）。
66. graphs 键必需：graph ID 到路径的映射。格式为 ./path/to/file.py:variable（Python）或 ./path/to/file.js:function（JS）。变量必须是 CompiledGraph 或返回它的函数。支持多个 graph。
67. env 键可选：指向 .env 文件的路径（字符串）或环境变量名到值的 inline mapping（对象）。本地由 langgraph dev 和 langgraph up 使用；langgraph deploy 会读取该文件并将变量添加为部署 secrets。
68. python_version 键可选：3.11、3.12 或 3.13，默认 3.11。
69. node_version 键可选：JS 项目的 Node.js 版本。
70. pip_config_file 键可选：自定义包索引的 pip 配置文件路径。
71. dockerfile_lines 键可选：在基础镜像 import 后追加的额外 Dockerfile 行数组，用于系统包、二进制文件或自定义设置。
72. 典型工作流第 1 步 Scaffold：langgraph new 从模板创建项目。
73. 典型工作流第 2 步 Configure：编辑 langgraph.json，设置 dependencies，将 graphs 指向编译后的 graph，添加 .env。
74. 典型工作流第 3 步 Develop：langgraph dev 快速本地迭代，热重载，无 Docker，端口 2024。
75. 典型工作流第 4 步 Validate：langgraph up --recreate 在生产类似 Docker 栈中测试，端口 8123，包含 Postgres。
76. 典型工作流第 5 步 Deploy：langgraph deploy 部署到 LangGraph Platform（LangSmith Deployments）。
77. 典型工作流第 6 步 Monitor：langgraph deploy logs -f 跟踪运行时日志；--type build 查看构建日志。
78. langgraph dev 与 langgraph up 对比：Docker 要求，dev 不需要，up 需要。
79. 安装对比：dev 用 pip install 'langgraph-cli[inmem]'，up 用 pip install langgraph-cli。
80. 主要用途对比：dev 用于快速开发与测试，up 用于生产类似验证。
81. 状态持久化对比：dev 使用内存或 pickle 到本地目录，up 使用 PostgreSQL。
82. 热重载对比：dev 默认是，up 可选（--watch）。
83. 默认端口对比：dev 为 2024，up 为 8123。
84. 资源占用对比：dev 轻量，up 较重（server、Postgres、Redis 容器）。
85. IDE 调试对比：dev 内置 DAP 支持（--debug-port），up 为容器调试。
86. 注意：langgraph deploy 需要 Docker；Apple Silicon（M1/M2/M3）还需要 Docker Buildx 交叉编译到 linux/amd64。
87. 注意：langgraph deploy 只能更新它自己创建的部署；通过 LangSmith UI 或 GitHub integration 创建的部署不能用 langgraph deploy 更新，应使用 UI。
88. 注意：dependencies 必须包含所有包；langgraph.json 的 dependencies 数组必须指向包配置所在位置（例如根目录用点号）。实际包从该位置的 pyproject.toml、requirements.txt 或 package.json 解析。
89. 注意：langgraph dev 不使用 Docker，直接在当前环境运行；如果代码依赖系统包（如 ffmpeg），必须本地安装。用 langgraph up 验证 Docker 构建。
90. 注意：JavaScript CLI 使用 npx @langchain/langgraph-cli <command>，或全局安装后使用 langgraphjs。
91. 注意：LANGSMITH_API_KEY 是 langgraph deploy 必需；langgraph dev 可选，没有也能运行，但 LangSmith 没有 trace。也可通过 LANGGRAPH_HOST_API_KEY 或 LANGCHAIN_API_KEY 设置。

适用边界 · 注意事项

• 未使用 LangGraph 或不打算安装/使用 langgraph-cli 时，不适用。
• 目标部署不是由 langgraph deploy 创建，而是通过 LangSmith UI 或 GitHub integration 创建时，不能用 langgraph deploy 更新，不适用。
• 没有 Docker 却需要 langgraph deploy/up，或 Apple Silicon 上没有 Docker Buildx 做 linux/amd64 交叉编译时，不适用。