第 0 章 · 环境准备

🎯 本章目标

把开发环境搭起来，跑通第一个 LangGraph。这一章不涉及概念，纯粹是"把机器点着"。

跟着做完，你会得到：

一个能跑 TypeScript 的 Node 环境
一份填好密钥的 .env 配置
一条命令，能验证全书 40+ 个示例是否都能跑通

预计耗时：10 分钟（主要花在 npm install 上）

一、你需要准备什么

项目	要求	检查命令
Node.js	>= 20（推荐 22 或 24）	`node -v`
npm	随 Node 自带即可	`npm -v`
大模型服务	任意兼容 OpenAI 接口的服务商	见下
网络	能访问 npm 源（国内可用镜像）	`npm config get registry`

⚠️ Node 版本是硬要求。LangGraph.js v1 依赖 Node 18+ 的新特性，Node 16 会直接报错。本书所有示例在 Node v24.18.0 上验证通过。
如果你用 nvm 管理 Node：nvm install 22 && nvm use 22

关于大模型服务商

本书不绑定任何一家服务商。只要对方提供兼容 OpenAI 协议的接口（即 /v1/chat/completions），改两行 .env 就能切换。

书里默认用 DeepSeek（因为便宜、国内直连、支持工具调用），但换成硅基流动、DashScope、火山方舟、Kimi、智谱、本地 Ollama……都只是改 .env 的事，代码一行都不用动。

服务商	`AI_ENDPOINT`	`AI_MODEL` 示例
DeepSeek	`https://api.deepseek.com/v1`	`deepseek-chat`
硅基流动	`https://api.siliconflow.cn/v1`	`Qwen/Qwen3-8B`
阿里云百炼	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-plus`
智谱	`https://open.bigmodel.cn/api/paas/v4`	`glm-4-flash`
本地 Ollama	`http://localhost:11434/v1`	`qwen2.5:7b`

💡 选模型的硬性要求：必须支持 Function Calling（工具调用）。本书从第 1 章开始就在用工具，不支持工具调用的模型跑不过去。检测方法：模型官方文档里搜 "function calling" 或 "tool use"。

二、四步把机器点着

第 1 步：拿到代码

从任一仓库克隆（两个仓库内容完全一致，国内访问 Gitee 更快）：

bash

# 1. 克隆（两个地址选一个，内容同步）
git clone https://github.com/cleversnail/LangGraph_js_cn.git
cd LangGraph_js_cn

# 或国内（Gitee，通常更快）
# git clone https://gitee.com/snail_wn/lang-graph_js_cn.git
# cd lang-graph_js_cn

第 2 步：安装依赖

bash

npm install

💡 如果卡住不动，换国内镜像：
bash
npm config set registry https://registry.npmmirror.com
npm install
1
2
关于 npm warn allow-scripts 提示：新版 npm 出于安全考虑会拦下依赖的安装脚本，属于正常提示，不影响本书示例（better-sqlite3 用的是预编译二进制，第 4 章的 SQLite 示例已验证可用）。

第 3 步：配置密钥

bash

cp .env.example .env

然后用编辑器打开 .env，把 AI_API_KEY 换成你自己的密钥：

ini

AI_API_KEY=sk-你的密钥
AI_ENDPOINT=https://api.deepseek.com/v1
AI_MODEL=deepseek-chat

🔒 .env 已经被 .gitignore 排除，不会被提交到仓库。请永远不要把密钥写进代码里。

第 4 步：跑通第一个图

bash

npx tsx 01-first-graph/code/01-hello-graph.ts

看到下面这段，说明环境完全就绪：

========================================================================
  示例 1：第一个 LangGraph（不使用大模型）
========================================================================

👤 输入：{ name: "蜗牛" }

   [节点 sayHello] 收到的状态：{"name":"蜗牛"}
   [节点 sayBye] 收到的状态：{"name":"蜗牛","greeting":"你好，蜗牛！"}

📦 最终状态： {
  "name": "蜗牛",
  "greeting": "你好，蜗牛！ 再见！"
}

✅ 结果：你好，蜗牛！ 再见！

注意：这个示例不调用大模型，所以即使 .env 还没配好也能跑。它验证的是"Node + TypeScript + LangGraph 装好了"。

再跑一个真正调用模型的，确认密钥没问题：

bash

npx tsx 01-first-graph/code/02-llm-graph.ts

如果输出里有正常的中文回答，说明密钥、接口地址、模型名三项都对了。

三、一键验证全书示例

想确认每一个示例都能跑通（会真实消耗 API 额度，约 15-25 分钟）：

bash

npm run verify

它会逐个运行 scripts/verify-examples.sh 里登记的所有示例，按三级判定给结论：

判定	含义
✅ PASS	进程正常退出，输出看起来合理
⚠️ SUSPECT	进程没崩、也没报错，但输出明显不对（比如模型没调用工具、正文为空、解析失败）
❌ FAIL	非零退出，或出现真正的运行时故障

为什么要单独设一个"可疑"等级？因为有些 bug 是静悄悄地错：进程 exit=0、也不抛异常，但结果完全不对。只看退出码是抓不到的。这是本书所有"真实输出"能站得住脚的保障机制。

类型检查（可选，验证所有 .ts 的类型正确）：

bash

npm run typecheck

四、仓库结构

LangGraph_js_cn/
├── 00-course-setup/                第 0 章（本章）
├── 01-first-graph/                 第 1 章 · 第一个图
│   ├── README.md                   ← 章节正文（讲解 + 完整代码 + 真实输出）
│   └── code/                       ← 可运行的 .ts 源文件
│       ├── 01-hello-graph.ts
│       └── ...
├── 02-state-and-reducers/
├── 03-edges-and-control-flow/
├── 04-persistence-and-memory/
├── 05-human-in-the-loop/
├── 06-streaming/
├── 07-multi-agent/
├── 08-production/
├── lib/                            共享工具（全书复用的模型工厂）
│   ├── env.ts                      读 .env
│   └── model.ts                    createModel() / banner()
├── docs/                           VitePress 电子书站点源码
├── scripts/
│   ├── verify-examples.sh          一键验证所有示例
│   ├── deploy-github.sh            发布到 GitHub Pages
│   └── deploy-tencent.sh           发布到腾讯云
├── .env.example                    环境变量模板
└── package.json

五、这本书怎么读

推荐节奏：每章"先跑、再看、最后改"。

先跑：进 code/ 目录，照着正文的运行命令把示例跑一遍，看真实输出
再看：回头读正文讲解，把"为什么这么写"对上
最后改：改点东西再跑一次。能改坏的代码，才是你学过的代码

关于"真实输出"的承诺

本书正文里所有标注"真实输出"的代码块，都是实际运行时从终端复制出来的，不是人工编造的"预期输出"。它们带时间戳、带模型当时的具体措辞、甚至带模型的思考过程 —— 所以你的运行结果不会逐字一样（模型输出天然有随机性），但结构、行数、关键结论一定一致。

代码约定

约定	说明
完整可运行	正文代码块含完整 import 和模型初始化，复制即能跑
无省略号	不出现 `...` 省略代码，需要简写会明确标注「节选」并指向 `code/` 下的完整文件
真实输出	每个示例都附「运行命令 + 真实输出」
路径约定	运行命令一律从项目根目录执行
共享代码	模型创建统一走 `lib/model.ts`，密钥统一走 `.env`

六、常见问题（FAQ）

Q1：报错 `缺少环境变量 AI_API_KEY`

.env 没建或没填。cp .env.example .env 后填入密钥。

Q2：报错 401 / Unauthorized

密钥错了，或者 AI_ENDPOINT 与服务商对不上。注意有些服务商的地址末尾要带 /v1，有些不带。

Q3：报错 `model not found` / 404

AI_MODEL 的名字写错了。模型名必须和服务商文档里完全一致，大小写、斜杠都算数（例如硅基流动是 Qwen/Qwen3-8B，带斜杠）。

Q4：模型回答是空的（没有报错，就是没内容）

几乎一定是 maxTokens 设太小。推理型模型（如 DeepSeek 的推理模型）的思维链也占用 maxTokens 额度，额度被思考花光，正文就空了 —— 而且不报错。把 maxTokens 调大（比如 2048 以上），或者干脆不设。

Q5：第 7 章的 supervisor / swarm 示例跑不了

这两个能力在独立的包里，已写进 package.json。重跑一次 npm install 即可。

Q6：第 4 章 SQLite 报错 `Cannot find module 'better-sqlite3'`

在项目根目录重跑 npm install。如果是在 Apple Silicon 上编译失败，确认 Node 版本 >= 20。

Q7：`npm run verify` 中途某些示例判为 SUSPECT

先看它打印的"可疑输出"关键词，多数是模型的随机性导致（比如某次没调用工具）。单独把那个文件再跑一次，如果通过了就是偶发。若稳定失败，欢迎提 Issue。

七、下一步

环境已经就绪。下一章我们正式进入 LangGraph：为什么"链"不够用、图到底由什么组成、以及那个只有两个节点却能撑起整个"智能体"概念的 ReAct 图。

第 0 章 · 环境准备 ​

🎯 本章目标 ​

一、你需要准备什么 ​

关于大模型服务商 ​

二、四步把机器点着 ​

第 1 步：拿到代码 ​

第 2 步：安装依赖 ​

第 3 步：配置密钥 ​

第 4 步：跑通第一个图 ​

三、一键验证全书示例 ​

四、仓库结构 ​

五、这本书怎么读 ​

六、常见问题（FAQ） ​

Q1：报错 缺少环境变量 AI_API_KEY ​

Q2：报错 401 / Unauthorized ​

Q3：报错 model not found / 404 ​

Q4：模型回答是空的（没有报错，就是没内容） ​

Q5：第 7 章的 supervisor / swarm 示例跑不了 ​

Q6：第 4 章 SQLite 报错 Cannot find module 'better-sqlite3' ​

Q7：npm run verify 中途某些示例判为 SUSPECT ​

七、下一步 ​

第 0 章 · 环境准备

🎯 本章目标

一、你需要准备什么

关于大模型服务商

二、四步把机器点着

第 1 步：拿到代码

第 2 步：安装依赖

第 3 步：配置密钥

第 4 步：跑通第一个图

三、一键验证全书示例

四、仓库结构

五、这本书怎么读

六、常见问题（FAQ）

Q1：报错 `缺少环境变量 AI_API_KEY`

Q2：报错 401 / Unauthorized

Q3：报错 `model not found` / 404

Q4：模型回答是空的（没有报错，就是没内容）

Q5：第 7 章的 supervisor / swarm 示例跑不了

Q6：第 4 章 SQLite 报错 `Cannot find module 'better-sqlite3'`

Q7：`npm run verify` 中途某些示例判为 SUSPECT

七、下一步