环境搭建与第一个程序

bughou
7 阅读8分钟

万事俱备，只欠东风。这一章我们将从零搭建 LangChain.js 的开发环境，并写出你的第一个 AI 对话程序。全程跟着做，15 分钟后你就能和 AI 聊天了。

2.1 Node.js 20+ 环境安装

LangChain.js 运行在 Node.js 环境中，要求版本 20 或以上。

检查已有版本

打开终端，输入以下命令：

node -v

如果输出类似 v20.x.x 或 v22.x.x，说明你的 Node.js 版本已经满足要求，可以跳到 2.2 节。

如果提示 command not found 或版本低于 20，请按下面的步骤安装。

macOS 安装

推荐方式：使用 nvm（Node Version Manager）

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 2. 重新打开终端，或执行以下命令使 nvm 生效
source ~/.zshrc   # 如果你用的是 zsh（macOS 默认）
# source ~/.bashrc  # 如果你用的是 bash

# 3. 安装 Node.js 20
nvm install 20

# 4. 设置为默认版本
nvm alias default 20

# 5. 验证安装
node -v   # 应输出 v20.x.x
npm -v    # 应输出 10.x.x

备选方式：使用 Homebrew

brew install node@20

Windows 安装

推荐方式：官方安装包

  1. 访问 Node.js 官网
  2. 下载 LTS（长期支持） 版本的安装包
  3. 双击运行安装程序，一路点击"Next"
  4. 安装完成后，打开 PowerShell 或 命令提示符，验证：
node -v   # 应输出 v20.x.x
npm -v    # 应输出 10.x.x

备选方式：使用 nvm-windows

# 先从 https://github.com/coreybutler/nvm-windows/releases 下载安装 nvm-windows
nvm install 20
nvm use 20

Linux 安装

# 使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm alias default 20

# 或使用系统包管理器（Ubuntu/Debian 示例）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

为什么需要 Node.js 20+

特性说明
原生 ES ModulesLangChain.js 使用 ESM 模块系统
原生 fetch APINode.js 18+ 内置 fetch，LangChain.js 依赖此 API 调用模型接口
性能优化V8 引擎升级，异步性能更好
LTS 支持Node.js 20 是长期支持版本，稳定且安全

2.2 项目初始化与包安装（langchain、@langchain/core）

创建项目目录

# 创建项目文件夹
mkdir my-langchain-app
cd my-langchain-app

# 初始化 npm 项目
npm init -y

配置 TypeScript

本小册的所有代码示例均使用 TypeScript 编写，它能提供更好的类型安全和 IDE 智能提示。

# 安装 TypeScript 和 tsx（用于直接运行 .ts 文件）
npm install -D typescript tsx @types/node

# 创建 tsconfig.json
npx tsc --init

编辑 tsconfig.json，确保以下配置：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "resolveJsonModule": true,
    "declaration": true,
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

在 package.json 中添加 type 字段和运行脚本：

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "start": "tsx src/index.ts"
  }
}

安装 LangChain.js

# 核心包（必装）
npm install langchain @langchain/core

# Zod —— 用于定义工具和结构化输出的 Schema
npm install zod

包的职责分工：

  • langchain：核心框架，提供 createAgent、tool 等高层 API
  • @langchain/core：底层核心，提供消息类型、Runnable 接口等基础设施
  • zod：Schema 验证库，LangChain.js 用它定义工具参数和结构化输出格式

安装模型提供商集成包

LangChain.js 的模型集成是按提供商分包的，你需要安装你使用的模型对应的包：

# 根据你的模型提供商，选择安装（至少安装一个）

# OpenAI（GPT-4o 等）
npm install @langchain/openai

# Anthropic（Claude 系列）
npm install @langchain/anthropic

# Google（Gemini 系列）
npm install @langchain/google-genai

💡 提示：如果你不确定选哪个，推荐先安装 @langchain/openai——OpenAI 的文档和社区资源最丰富，适合入门学习。

安装完成后的项目结构

my-langchain-app/
├── node_modules/
├── src/
│   └── (我们马上在这里写代码)
├── package.json
├── package-lock.json
└── tsconfig.json

2.3 获取并配置 API Key（OpenAI / Anthropic / Google）

要让你的程序调用 LLM 模型，需要先获取对应提供商的 API Key。

OpenAI API Key

  1. 访问 platform.openai.com/api-keys
  2. 注册/登录 OpenAI 账号
  3. 点击 "Create new secret key"
  4. 复制生成的 Key（以 sk- 开头）

Anthropic API Key

  1. 访问 console.anthropic.com/
  2. 注册/登录 Anthropic 账号
  3. 在 "API Keys" 页面创建新的 Key
  4. 复制生成的 Key（以 sk-ant- 开头）

Google AI API Key

  1. 访问 aistudio.google.com/app/apikey
  2. 登录 Google 账号
  3. 点击 "Create API Key"
  4. 复制生成的 Key

配置环境变量

⚠️ 安全警告：永远不要把 API Key 直接写在代码中或提交到 Git 仓库！

推荐方式：使用 .env 文件

在项目根目录创建 .env 文件：

# .env 文件
# 根据你使用的模型提供商，配置对应的 Key

# OpenAI
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Anthropic
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google
GOOGLE_API_KEY=AIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

安装 dotenv 包来加载环境变量：

npm install dotenv

在代码入口处加载：

// src/index.ts
import "dotenv/config";

// 现在 process.env.OPENAI_API_KEY 就可以访问了

别忘了将 .env 加入 .gitignore：

# 创建 .gitignore 文件
echo ".env" >> .gitignore
echo "node_modules" >> .gitignore
echo "dist" >> .gitignore

验证 API Key

创建一个简单的测试脚本来验证 Key 是否配置正确：

// src/test-key.ts
import "dotenv/config";

// 检查环境变量是否存在
const keys = {
  OpenAI: process.env.OPENAI_API_KEY,
  Anthropic: process.env.ANTHROPIC_API_KEY,
  Google: process.env.GOOGLE_API_KEY,
};

for (const [provider, key] of Object.entries(keys)) {
  if (key) {
    console.log(`✅ ${provider} API Key 已配置（${key.slice(0, 8)}...）`);
  } else {
    console.log(`⬜ ${provider} API Key 未配置`);
  }
}

运行测试：

npx tsx src/test-key.ts

你应该看到类似的输出：

✅ OpenAI API Key 已配置（sk-xxxxxx...）
⬜ Anthropic API Key 未配置
⬜ Google API Key 未配置

2.4 Hello LangChain：你的第一个 AI 对话程序

环境准备就绪，现在来写你的第一个 LangChain.js 程序！

示例 1：最简单的 AI 对话

创建文件 src/index.ts：

// src/index.ts
import "dotenv/config";
import { ChatOpenAI } from "@langchain/openai";

// 创建模型实例
const model = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0.7, // 控制回复的随机性（0=确定性，1=更随机）
});

// 调用模型
const response = await model.invoke("你好！请用一句话介绍你自己。");

// 输出回复
console.log(response.content);

运行：

npx tsx src/index.ts

你应该看到类似的输出：

你好！我是一个由 OpenAI 开发的 AI 语言模型，可以帮你回答问题、写作、编程等各种任务。

🎉 恭喜！你的第一个 LangChain.js 程序运行成功了！

示例 2：多轮对话

AI 的强大之处在于能够理解上下文。让我们来实现一个多轮对话：

// src/chat.ts
import "dotenv/config";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, AIMessage, SystemMessage } from "@langchain/core/messages";

const model = new ChatOpenAI({ model: "gpt-4o" });

// 构建消息历史
const messages = [
  new SystemMessage("你是一个友好的 AI 助手，请用中文简洁回答。"),
  new HumanMessage("我叫小明，请记住我的名字。"),
];

// 第一轮对话
const response1 = await model.invoke(messages);
console.log("AI:", response1.content);

// 将 AI 的回复加入消息历史
messages.push(new AIMessage(response1.content as string));

// 第二轮对话 —— AI 应该记住你的名字
messages.push(new HumanMessage("我叫什么名字？"));
const response2 = await model.invoke(messages);
console.log("AI:", response2.content);

运行：

npx tsx src/chat.ts

输出类似：

AI: 你好小明！我已经记住你的名字了，有什么可以帮你的吗？
AI: 你叫小明。

关键概念：AI 本身没有"记忆"，它是通过接收完整的消息历史来"记住"之前的对话的。消息管理是 LangChain.js 的核心概念之一，我们会在第 4 章详细讲解。

示例 3：你的第一个 Agent

这是 LangChain.js v1 的核心用法——用 createAgent 创建一个能使用工具的智能代理：

// src/agent.ts
import "dotenv/config";
import { createAgent, tool } from "langchain";
import * as z from "zod";

// 定义一个天气查询工具
const getWeather = tool(
  ({ city }) => {
    // 这里用模拟数据，实际项目中你可以调用真实的天气 API
    const weatherData: Record<string, string> = {
      北京: "晴天，25°C",
      上海: "多云，22°C",
      广州: "小雨，28°C",
      深圳: "阴天，27°C",
    };
    return weatherData[city] || `抱歉，暂无 ${city} 的天气数据`;
  },
  {
    name: "get_weather",
    description: "查询指定城市的当前天气信息",
    schema: z.object({
      city: z.string().describe("要查询天气的城市名称"),
    }),
  }
);

// 定义一个计算器工具
const calculator = tool(
  ({ expression }) => {
    try {
      // 注意：生产环境请使用安全的数学表达式解析库
      const result = new Function(`return ${expression}`)();
      return `计算结果：${expression} = ${result}`;
    } catch {
      return "计算出错，请检查表达式";
    }
  },
  {
    name: "calculator",
    description: "计算数学表达式",
    schema: z.object({
      expression: z.string().describe("要计算的数学表达式，如 '2 + 3 * 4'"),
    }),
  }
);

// 创建 Agent
const agent = createAgent({
  model: "gpt-4o",
  tools: [getWeather, calculator],
});

// 让 Agent 处理问题 —— 它会自动判断是否需要调用工具
console.log("--- 问题 1：查天气 ---");
const result1 = await agent.invoke({
  messages: [{ role: "user", content: "北京今天天气怎么样？" }],
});
// 获取最后一条 AI 消息
const lastMessage1 = result1.messages[result1.messages.length - 1];
console.log("AI:", lastMessage1.content);

console.log("\n--- 问题 2：做计算 ---");
const result2 = await agent.invoke({
  messages: [{ role: "user", content: "帮我算一下 (15 + 27) * 3 等于多少" }],
});
const lastMessage2 = result2.messages[result2.messages.length - 1];
console.log("AI:", lastMessage2.content);

console.log("\n--- 问题 3：普通聊天（不需要工具）---");
const result3 = await agent.invoke({
  messages: [{ role: "user", content: "给我讲个笑话" }],
});
const lastMessage3 = result3.messages[result3.messages.length - 1];
console.log("AI:", lastMessage3.content);

运行：

npx tsx src/agent.ts

输出类似：

--- 问题 1：查天气 ---
AI: 北京今天的天气是晴天，气温 25°C，适合出行！

--- 问题 2：做计算 ---
AI: (15 + 27) × 3 = 126

--- 问题 3：普通聊天（不需要工具）---
AI: 好的，来一个：程序员最讨厌什么？——加班写文档。

Agent 的智能之处：注意观察，Agent 会自动判断是否需要调用工具——查天气时调用了 get_weather 工具，做计算时调用了 calculator 工具，而普通聊天则直接回复，没有调用任何工具。这就是"智能代理"的核心能力。

切换模型提供商

如果你使用的是 Anthropic 或 Google，只需修改模型名称：

// 使用 Anthropic Claude（需要先 npm install @langchain/anthropic）
const agent = createAgent({
  model: "claude-sonnet-4-6",
  tools: [getWeather, calculator],
});

// 使用 Google Gemini（需要先 npm install @langchain/google-genai）
const agent = createAgent({
  model: "gemini-2.5-pro",
  tools: [getWeather, calculator],
});

这就是 LangChain.js 标准化模型接口的威力——切换模型只需改一个字符串！

2.5 开发环境推荐与调试技巧

IDE 推荐

IDE推荐度说明
VS Code⭐⭐⭐⭐⭐免费、插件丰富、TypeScript 支持极好
WebStorm⭐⭐⭐⭐JetBrains 出品，重构功能强大
Cursor⭐⭐⭐⭐AI 辅助编程，写 LangChain 代码更快

VS Code 推荐插件

插件用途
TypeScript Importer自动导入 TypeScript 模块
ESLint代码质量检查
Prettier代码格式化
DotENV.env 文件语法高亮
Error Lens在代码行内显示错误信息

调试技巧

技巧 1：使用 LangSmith 追踪（推荐）

LangSmith 是官方提供的可视化调试工具，可以让你看到 Agent 每一步的执行过程：

# 在 .env 中添加 LangSmith 配置
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx

💡 在 smith.langchain.com/ 注册免费账号即可获取 API Key。

技巧 2：使用 verbose 模式

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "gpt-4o",
  verbose: true, // 开启详细日志，会打印每次模型调用的输入输出
});

技巧 3：使用 tsx watch 模式

# watch 模式：修改代码后自动重新运行
npx tsx watch src/index.ts

技巧 4：VS Code 断点调试

在 .vscode/launch.json 中添加：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug TypeScript",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["tsx", "${file}"],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

然后在代码中设置断点，按 F5 启动调试。

常见问题排查

❓ 报错：Cannot find module 'langchain'

# 确认是否安装了依赖
npm install langchain @langchain/core

# 确认 node_modules 存在
ls node_modules/langchain

❓ 报错：OPENAI_API_KEY is not set

# 检查 .env 文件是否存在
cat .env

# 确认代码中加载了 dotenv
# 文件开头应有：import "dotenv/config";

❓ 报错：ERR_MODULE_NOT_FOUND

# 确认 package.json 中有 "type": "module"
cat package.json | grep type

❓ 报错：fetch is not defined

# 你的 Node.js 版本可能低于 18，请升级
node -v
# 如果低于 v18，请参照 2.1 节升级 Node.js

❓ API 调用超时

// 如果在国内网络环境，可能需要配置代理
// 方法 1：设置环境变量
// HTTPS_PROXY=http://127.0.0.1:7890

// 方法 2：使用兼容 OpenAI 接口的国内服务
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "gpt-4o",
  configuration: {
    baseURL: "https://your-proxy-api.com/v1", // 替换为你的代理地址
  },
});

本章实战项目：交互式 AI 聊天终端

让我们把本章学到的知识综合起来，构建一个可以在终端里实时聊天的 AI 助手：

// src/terminal-chat.ts
import "dotenv/config";
import { createAgent, tool } from "langchain";
import * as z from "zod";
import * as readline from "node:readline";

// ─── 工具定义 ─────────────────────────────────────

const getTime = tool(
  () => {
    const now = new Date();
    return `当前时间：${now.toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}`;
  },
  {
    name: "get_current_time",
    description: "获取当前的日期和时间",
    schema: z.object({}),
  }
);

const calculate = tool(
  ({ expression }) => {
    try {
      const result = new Function(`return ${expression}`)();
      return `${expression} = ${result}`;
    } catch {
      return "计算出错，请检查表达式格式";
    }
  },
  {
    name: "calculator",
    description: "计算数学表达式",
    schema: z.object({
      expression: z.string().describe("数学表达式，如 '(10 + 5) * 2'"),
    }),
  }
);

// ─── 创建 Agent ───────────────────────────────────

const agent = createAgent({
  model: "gpt-4o",
  tools: [getTime, calculate],
});

// ─── 对话历史 ─────────────────────────────────────

const conversationHistory: Array<{ role: string; content: string }> = [
  {
    role: "system",
    content: "你是一个友好的 AI 助手，名叫小 Lang。请用中文简洁明了地回答问题。",
  },
];

// ─── 终端交互 ─────────────────────────────────────

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

console.log("╔══════════════════════════════════════════╗");
console.log("║     🤖 小 Lang - 你的 AI 聊天助手        ║");
console.log("║     输入消息开始聊天，输入 'exit' 退出     ║");
console.log("╚══════════════════════════════════════════╝");
console.log();

const askQuestion = () => {
  rl.question("你: ", async (input) => {
    const trimmed = input.trim();

    if (trimmed.toLowerCase() === "exit") {
      console.log("\n👋 再见！期待下次与你聊天。");
      rl.close();
      return;
    }

    if (!trimmed) {
      askQuestion();
      return;
    }

    // 将用户消息加入历史
    conversationHistory.push({ role: "user", content: trimmed });

    try {
      // 调用 Agent
      const result = await agent.invoke({
        messages: conversationHistory,
      });

      // 获取 AI 回复
      const aiMessages = result.messages.filter(
        (msg: any) => msg._getType?.() === "ai" || msg.role === "assistant"
      );
      const lastAIMessage = aiMessages[aiMessages.length - 1];
      const aiContent = typeof lastAIMessage.content === "string"
        ? lastAIMessage.content
        : JSON.stringify(lastAIMessage.content);

      console.log(`\n🤖 小 Lang: ${aiContent}\n`);

      // 将 AI 回复加入历史
      conversationHistory.push({ role: "assistant", content: aiContent });
    } catch (error: any) {
      console.log(`\n❌ 出错了: ${error.message}\n`);
    }

    askQuestion();
  });
};

askQuestion();

运行这个程序：

npx tsx src/terminal-chat.ts

你将看到一个交互式聊天界面：

╔══════════════════════════════════════════╗
║     🤖 小 Lang - 你的 AI 聊天助手        ║
║     输入消息开始聊天，输入 'exit' 退出     ║
╚══════════════════════════════════════════╝

你: 你好，你是谁？

🤖 小 Lang: 你好！我是小 Lang，你的 AI 聊天助手。我可以帮你回答问题、查询时间、做数学计算等。有什么可以帮你的吗？

你: 现在几点了？

🤖 小 Lang: 当前时间是 2026/3/27 10:30:00。

你: 帮我算一下 125 * 8 + 37

🤖 小 Lang: 125 × 8 + 37 = 1037

你: exit

👋 再见！期待下次与你聊天。

项目文件总结

完成本章后，你的项目结构应该是：

my-langchain-app/
├── .env                  # API Key 配置（不提交到 Git）
├── .gitignore            # Git 忽略规则
├── .vscode/
│   └── launch.json       # VS Code 调试配置
├── node_modules/
├── src/
│   ├── index.ts          # 示例 1：最简单的 AI 对话
│   ├── chat.ts           # 示例 2：多轮对话
│   ├── agent.ts          # 示例 3：你的第一个 Agent
│   ├── test-key.ts       # API Key 验证脚本
│   └── terminal-chat.ts  # 实战项目：交互式聊天终端
├── package.json
├── package-lock.json
└── tsconfig.json

本章小结

在这一章中，我们完成了以下内容：

完成项说明
✅ Node.js 20+ 环境安装支持 macOS / Windows / Linux
✅ TypeScript 项目初始化tsconfig.json + tsx 运行器
✅ LangChain.js 包安装langchain + @langchain/core + 模型集成包
✅ API Key 配置环境变量 + .env 文件
✅ 第一个 AI 对话使用 ChatOpenAI 进行简单对话
✅ 多轮对话使用消息历史实现上下文记忆
✅ 第一个 Agent使用 createAgent + tool 创建智能代理
✅ 交互式聊天终端完整的终端聊天应用

核心概念回顾

  • ChatOpenAI / ChatAnthropic / ChatGoogleGenerativeAI：不同模型提供商的聊天模型类
  • createAgent：LangChain.js v1 创建 Agent 的核心方法
  • tool：定义 Agent 可以使用的工具
  • messages：AI 通过消息历史来理解对话上下文

在下一章中，我们将深入学习 LangChain.js 的核心组件——模型（Models），了解如何精确控制 AI 的行为参数，以及如何在多个模型提供商之间无缝切换。

上一章：第 1 章：走进 AI 开发的世界

下一章：第 3 章：模型（Models）—— AI 的大脑

avatar
文章
阅读
粉丝