环境搭建

从零开始搭建 LangGraphJS 开发环境，包含详细的安装步骤和配置指南

引言

工欲善其事，必先利其器。在开始 LangGraph.js 的学习之旅之前，我们需要搭建一个完整的开发环境。本章将提供清晰的环境搭建指南，确保你能够顺利开始开发工作。

📚 学习目标

学完这篇文章后，你将能够：

配置 Node.js 开发环境
创建并初始化一个 LangGraph 项目
安装核心依赖并理解其作用
运行验证脚本确保环境正常

前置知识

你需要了解：

基本的命令行操作
npm/pnpm 包管理器的基本使用

1 系统要求

Node.js: 版本 18.0.0 或更高（推荐最新 LTS 版本）
包管理器: 推荐 pnpm（更快、更省空间），也可以使用 npm 或 yarn
编辑器: VS Code（推荐安装 TypeScript 插件）
操作系统: Windows/macOS/Linux 均可（建议保持系统 TLS/证书链正常，避免 HTTPS 请求失败）

[!TIP] 检查版本命令：node -v 和 npm -v

2 快速开始

创建新项目

# 1. 创建目录
mkdir my-langgraph-project
cd my-langgraph-project

# 2. 初始化
pnpm init

# 3. 安装核心依赖
pnpm add @langchain/langgraph @langchain/core @langchain/openai zod dotenv

# 4. 安装开发依赖
pnpm add -D typescript @types/node esno

如果你使用 npm 或 yarn，只需将 pnpm 替换为相应命令即可。

ℹ️ 为什么推荐 pnpm？

更快的安装速度：利用硬链接和内容寻址存储
节省磁盘空间：全局存储，避免重复下载
更严格的依赖管理：防止幽灵依赖问题

依赖说明

包名	作用
`@langchain/langgraph`	核心图框架
`@langchain/core`	基础抽象（Messages, Tools 等）
`@langchain/openai`	OpenAI 模型集成
`zod`	Schema 定义和校验
`dotenv`	环境变量加载
`esno`	直接运行 TS 文件（基于 esbuild，超快）

3 可选依赖：按需加，不要一次装一堆

很多同学刚开始会把一堆依赖全装上，然后遇到冲突/版本问题。

更推荐的方式是：先跑通最小闭环，再按功能逐步加。

场景	你可能需要的包	说明
用 Claude	`@langchain/anthropic`	替换/补充 OpenAI
用 Gemini	`@langchain/google-genai`	替换/补充 OpenAI
用本地模型	`@langchain/ollama`	本地推理（取决于你的模型部署）
用社区工具/检索器	`@langchain/community`	常见工具集合
MCP 工具生态	`@langchain/mcp-adapters`	连接 MCP server

4 环境配置

API 密钥设置

创建 .env 文件：

# .env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 如果使用 LangSmith 调试
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2-xxxxxxxxxxxxxx

[!WARNING] 请务必将 .env 添加到 .gitignore 文件中，防止密钥泄露！

同时建议你把“.env 管理”做成习惯：

本地开发：.env
CI/生产：平台环境变量（或密钥管理服务）
永远不要：把 Key 写进源码 / 把 .env 提交到 git

TypeScript 配置

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"]
}

5 推荐项目结构（越早规范越省事）

如果你只是做小 demo，src/index.ts 一个文件也能跑。

但只要你开始引入工具、持久化、多 agent，建议用一个“可扩展”的目录：

my-langgraph-project/
  src/
    graphs/        # Graph 组装（compile）
    nodes/         # 节点函数（可测试）
    tools/         # 工具定义（超时/重试最常见）
    state/         # Annotation / state schema
    index.ts
  tests/
  .env
  tsconfig.json
  package.json

你可以把它类比成前端：

nodes ≈ 业务逻辑 hooks/services
tools ≈ 外部 API client
state ≈ 你的 store/schema

6 验证安装

创建 src/index.ts：

import 'dotenv/config';
import { StateGraph, Annotation, START, END } from '@langchain/langgraph';
import { HumanMessage } from '@langchain/core/messages';
import { ChatOpenAI } from '@langchain/openai';

// 1. 定义状态
const StateAnnotation = Annotation.Root({
  message: Annotation<string>,
});

// 2. 创建节点
const llmNode = async (state: typeof StateAnnotation.State) => {
  const model = new ChatOpenAI({ model: 'gpt-3.5-turbo' });
  const response = await model.invoke([new HumanMessage(state.message)]);
  return { message: response.content };
};

// 3. 构建图
const graph = new StateGraph(StateAnnotation)
  .addNode('llm', llmNode)
  .addEdge(START, 'llm')
  .addEdge('llm', END)
  .compile();

// 4. 运行
const result = await graph.invoke({ message: '你好！LangGraph' });
console.log('AI回复:', result.message);

运行测试：

pnpm esno src/index.ts

预期输出

如果一切配置正确，你应该看到类似输出：

AI回复: 你好！很高兴见到你。

如果看到 AI 的回复，恭喜你，环境搭建成功！🎉

7 常见问题排查（非常高频）

1. `OpenAI API key not found`

检查顺序建议是：

.env 文件是否在项目根目录
你是否在入口文件最早位置加载了 dotenv/config
环境变量名是否写对（例如 OPENAI_API_KEY）

2. HTTPS 请求失败/证书问题

通常出现在公司网络代理或系统证书链异常。建议先用最小脚本验证网络层是否 OK。

3. TypeScript 报错很多

优先确认：

tsconfig.json 的 moduleResolution 与你的运行方式匹配
Node 版本与 target 匹配

8 开发工具建议（可选，但很值）

VS Code 建议装：

ESLint
Prettier
DotENV（环境变量高亮）

并开启 formatOnSave（减少风格争论）。

🆘 获取帮助

如果在环境搭建过程中遇到问题：

检查文档：先查看官方文档和本指南
搜索问题：在 GitHub Issues 中搜索类似问题
社区求助：在 Discord 或论坛中寻求帮助

💡 练习题

操作题：尝试将示例代码中的模型改为 gpt-4o（如果你有权限），或者尝试更换 prompt。

点击查看答案
直接在模型初始化处把 model 改为 gpt-4o，无权限时保持原模型仅替换 prompt 内容也可。建议记录同一输入下两版输出，比较风格和稳定性差异。
排错题：如果运行报错 OpenAI API key not found，你应该检查哪些地方？（提示：.env 文件位置、dotenv 加载、API Key 是否有余额）

点击查看答案
依次检查：项目根目录 .env 是否存在、键名是否为 OPENAI_API_KEY、程序入口是否执行了 dotenv/config、终端环境是否覆盖了空值。另外确认 key 可用且额度正常，否则会出现“看似读取成功但请求失败”。
结构题：按“推荐项目结构”创建 nodes/ 和 tools/ 目录，并把 llmNode 移到 nodes/llm.ts（只需要做到能跑通）。

点击查看答案
迁移时重点是修正 import 路径与导出方式：nodes/llm.ts 导出 llmNode，主图文件改为从 nodes/llm 引入。跑通标准是编译无报错、invoke 能正常返回结果。

✅ 总结

本章要点：

成功的环境搭建是开发的第一步。
掌握 .env 管理密钥是安全开发的基础。
StateGraph 的最小化示例验证了核心依赖的可用性。

下一步：环境就绪，先从“核心概念”建立心智模型：

核心概念

登录以继续阅读

解锁完整文档、代码示例及更多高级功能。

立即登录