1. 项目缘起：为什么从LangChain-ts开始？

如果你和我一样，最近在捣鼓大语言模型应用开发，大概率会听到一个名字：LangChain。这个框架几乎成了连接LLM与外部世界事实上的标准。但当你兴冲冲地打开官方文档，准备大干一场时，可能会发现一个尴尬的现实——绝大多数教程、示例和社区讨论，都围绕着Python版本展开。对于像我这样，项目技术栈以Node.js为主，或者单纯就是更喜欢TypeScript的静态类型安全和现代前端生态的开发者来说，这无疑是个门槛。

这就是我决定系统学习并记录LangChain-ts（即LangChain的TypeScript/JavaScript版本）的初衷。Python生态固然强大，但Node.js在Web服务、CLI工具、桌面应用（如Electron）以及需要与现有前端/全栈项目无缝集成的场景下，有着不可替代的优势。LangChain-ts正是为了填补这一空白而生。然而，它的中文资料相对匮乏，环境配置的细节也散落在官方文档和各个Issue中。因此，这个系列的第一篇，我们不谈高深的Agent或复杂的RAG管道，就从最基础、也最容易踩坑的一步开始：环境安装与配置。我会把我从零搭建一个可运行、可调试的LangChain-ts开发环境过程中，遇到的所有问题、选择的方案以及背后的考量，毫无保留地分享出来。

2. 核心工具链选型与底层逻辑

在动手安装任何包之前，我们需要先理清整个技术栈的依赖关系。LangChain-ts不是一个孤立的库，它运行在Node.js的生态之上，并且严重依赖一系列现代JavaScript开发工具。盲目地npm install很可能导致版本冲突、类型错误或者构建失败。

2.1 Node.js版本管理：为什么不用系统自带的Node？

很多新手会直接使用操作系统自带的Node.js，或者从官网下载一个安装包。这为后续的依赖管理埋下了巨大的隐患。不同的项目可能需要不同版本的Node.js，而系统级的全局安装无法做到隔离。

我的选择是nvm（Node Version Manager）。这是一个命令行工具，允许你在同一台机器上安装和切换多个Node.js版本。它的优势显而易见：

• 项目隔离：为每个项目目录指定一个Node版本，互不干扰。
• 安全便捷：安装和切换版本无需sudo权限，避免污染系统目录。
• 社区主流：是Node.js社区事实上的标准版本管理工具。

对于macOS或Linux用户，安装nvm非常方便。打开终端，使用官方安装脚本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重启终端或执行source ~/.zshrc（或~/.bashrc）使配置生效。然后，安装一个与LangChain-ts兼容的Node.js长期支持版本。我推荐使用Node.js 18.x或20.x的LTS版本，因为它们提供了最佳的稳定性和生态兼容性。

nvm install 18 nvm use 18

你可以通过node -v和npm -v来验证安装是否成功。

注意：Windows用户可以使用nvm-windows这个移植版本，但请注意其命令和路径可能与原生nvm略有不同。另一个强大的跨平台选择是fnm（Fast Node Manager），速度更快，用法类似。

2.2 包管理器的抉择：npm, yarn, 还是 pnpm？

Node.js自带npm，但近年来yarn和pnpm因其更好的性能、更严格的依赖锁和更优的磁盘空间管理而备受青睐。对于LangChain-ts项目，我的建议是pnpm。

为什么是pnpm？

1. 磁盘效率：pnpm使用硬链接和符号链接在全局存储中管理依赖，同一个版本的包在磁盘上只保存一份，可以节省大量空间。这对于LangChain这类依赖树可能较深（包含各种LLM SDK、向量数据库客户端等）的项目尤其有益。
2. 安装速度：得益于其独特的链接机制，pnpm的安装速度通常比npm和yarn v1更快。
3. 严格性：pnpm默认创建非扁平化的node_modules结构，这能更好地避免幽灵依赖（即使用了一个未在package.json中声明的包）的问题，让依赖关系更清晰可预测。

安装pnpm很简单（假设你已安装Node.js）：

npm install -g pnpm

之后在项目中使用pnpm init来初始化项目，用pnpm add来安装包。

当然，使用npm或yarn（v1或berry）也完全可行。关键在于锁定依赖版本。无论你选择哪个，请务必确保生成的锁文件（package-lock.json,yarn.lock,pnpm-lock.yaml）被提交到版本控制中，这是保证团队协作和线上部署一致性的生命线。

2.3 TypeScript配置：不仅仅是tsc

LangChain-ts是用TypeScript编写的，这意味着我们的项目也需要配置TypeScript编译器。这一步是类型安全的核心。

首先，在项目根目录初始化TypeScript配置：

pnpm add -D typescript @types/node pnpm tsc --init

这会生成一个tsconfig.json文件。官方提供的配置可能很庞大，我们需要根据LangChain-ts应用的特点进行优化。下面是一个针对Node.js后端或工具类项目的推荐配置：

{ "compilerOptions": { "target": "ES2022", "module": "commonjs", "lib": ["ES2022"], "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "moduleResolution": "node", "allowSyntheticDefaultImports": true, "declaration": true, "declarationMap": true, "sourceMap": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "**/*.test.ts"] }

关键配置项解析：

• "target": "ES2022"：编译目标ECMAScript版本。ES2022提供了很多现代语法特性，且Node.js 18+完全支持。
• "module": "commonjs"：对于Node.js环境，CommonJS模块系统仍然是最稳定、兼容性最好的选择。如果你确定你的环境支持ES Modules（如使用了--experimental-modules标志或较新版本），可以尝试"node16"或"nodenext"。
• "rootDir"与"outDir"：清晰地分离源代码（src）和编译输出（dist），保持项目结构整洁。
• "skipLibCheck": true：这是一个重要的性能优化选项。它会跳过对.d.ts类型声明文件的类型检查。像LangChain这样依赖众多的大型库，开启全类型检查会极大拖慢编译速度。对于应用开发，开启此选项是安全且通用的做法。
• "resolveJsonModule": true：允许直接导入JSON文件。这在读取配置文件（如API密钥）时非常有用。

2.4 开发体验增强：ESLint与Prettier

对于严肃的项目，代码质量和风格一致性必不可少。ESLint负责检查代码中的潜在问题和风格问题，Prettier则专注于代码的自动格式化。

安装与配置：

pnpm add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-config-prettier

• eslint: ESLint核心。
• @typescript-eslint/parser: 使ESLint能解析TypeScript语法。
• @typescript-eslint/eslint-plugin: 提供针对TypeScript的linting规则。
• prettier: 代码格式化工具。
• eslint-config-prettier: 关闭所有与Prettier冲突的ESLint规则，让两者和谐共处。

创建.eslintrc.js配置文件：

module.exports = { parser: '@typescript-eslint/parser', extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier' // 必须放在最后，用于覆盖冲突规则 ], plugins: ['@typescript-eslint'], env: { node: true, es2022: true }, parserOptions: { ecmaVersion: 'latest', sourceType: 'module' }, rules: { // 可以在这里添加或覆盖规则 '@typescript-eslint/no-explicit-any': 'warn', // 将any警告而不是报错 } };

创建.prettierrc配置文件：

{ "semi": true, "trailingComma": "es5", "singleQuote": true, "printWidth": 100, "tabWidth": 2 }

最后，在package.json中添加脚本，方便使用：

{ "scripts": { "lint": "eslint src --ext .ts", "lint:fix": "eslint src --ext .ts --fix", "format": "prettier --write \"src/**/*.ts\"", "build": "tsc", "dev": "tsc --watch" } }

3. LangChain-ts核心库安装与版本策略

基础环境就绪后，终于可以安装LangChain-ts了。这里有一个非常重要的概念：LangChain-ts是一个由众多独立包组成的模块化框架。你不需要安装一个庞大的langchain包，而是按需安装你需要的功能模块。

3.1 理解包结构：@langchain/core 与 @langchain/community

从LangChain v0.1.0开始，其架构进行了重大重构，核心思想是分离关注点：

1. @langchain/core：这是框架的绝对核心。它定义了最基础的抽象，如BaseLanguageModel、BaseChatModel、BaseRetriever、BaseTool等，以及链条（Chain）、提示词模板（PromptTemplate）的核心逻辑。几乎任何LangChain应用都需要安装它。
2. @langchain/<integration>：这些是具体的集成包。例如：
   • @langchain/openai: 集成OpenAI的GPT系列模型。
   • @langchain/google-genai: 集成Google的Gemini模型。
   • @langchain/anthropic: 集成Claude模型。
   • @langchain/community: 这是一个“大杂烩”包，包含了大量第三方集成，比如各种向量数据库（Chroma, Pinecone）、文档加载器（PDF, CSV）、工具（SerpAPI, Wikipedia）等。对于初期探索，安装这个包很方便，但对于生产环境，建议只安装你需要的特定社区包以减少依赖体积。
3. langchain：这是一个“伞包”（umbrella package），它本身不包含太多代码，主要作用是重新导出（re-export）其他所有官方包（如core, openai等）的API。对于新手，或者想快速开始不想操心具体包名的场景，安装这个包最简单。但它会引入大量你可能用不到的依赖。

我的安装建议：对于学习和中型项目，一个平衡的方案是安装核心包、你计划使用的LLM提供商包，以及社区包。

pnpm add @langchain/core @langchain/openai @langchain/community

如果你想从最精简开始，可以只安装核心和OpenAI：

pnpm add @langchain/core @langchain/openai

3.2 版本管理与依赖解析

LangChain生态迭代非常快，保持版本一致性至关重要。强烈建议在安装时指定主版本号，并利用锁文件。

pnpm add @langchain/core@^0.1.0 @langchain/openai@^0.0.10

这里的^符号表示允许安装最新的次要版本和补丁版本（如0.1.x），但不会跳到0.2.0。这能在获得错误修复和新功能的同时，避免破坏性变更。

安装后，你的package.json会类似这样：

{ "dependencies": { "@langchain/core": "^0.1.0", "@langchain/openai": "^0.0.10", "@langchain/community": "^0.0.10" } }

而pnpm-lock.yaml（或等价的锁文件）则锁定了所有传递依赖的确切版本，这是项目可复现性的关键。

踩坑记录：我曾经在一个项目中混合使用了langchain（伞包）和独立的@langchain/openai包，由于它们内部引用的@langchain/core版本有细微差异，导致了难以追踪的运行时类型错误。教训是：在一个项目中，尽量统一使用一种引用方式（要么全部用独立包，要么只用伞包），并确保所有LangChain相关包的主版本号一致。

4. 环境变量管理与API密钥安全

任何LLM应用都绕不开API密钥。像OpenAI API Key这样的敏感信息，绝对不能硬编码在源代码中，否则一旦代码泄露，后果不堪设想。标准做法是使用环境变量。

4.1 使用dotenv管理本地环境

在开发环境中，我们使用dotenv库来从.env文件加载环境变量。

pnpm add dotenv

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

OPENAI_API_KEY=sk-your-actual-openai-api-key-here ANTHROPIC_API_KEY=your-anthropic-key LANGSMITH_API_KEY=your-langsmith-key # 其他配置...

重要：务必在.gitignore文件中添加.env，防止将其提交到版本库。

# .gitignore node_modules dist .env .env.local

在你的应用入口文件（如src/index.ts）的最顶部加载配置：

import * as dotenv from 'dotenv'; dotenv.config(); // 这会读取项目根目录的.env文件 // 现在可以通过 process.env 访问 const openAIApiKey = process.env.OPENAI_API_KEY; if (!openAIApiKey) { throw new Error('OPENAI_API_KEY is not defined in environment variables.'); }

4.2 结构化配置与验证

对于更复杂的项目，直接使用process.env会显得散乱，且缺乏验证。我推荐使用zod这个强大的模式验证库来定义和验证环境变量模式。

pnpm add zod

创建一个专门的配置文件，例如src/config.ts：

import { z } from 'zod'; import * as dotenv from 'dotenv'; dotenv.config(); const envSchema = z.object({ OPENAI_API_KEY: z.string().min(1, 'OpenAI API key is required'), ANTHROPIC_API_KEY: z.string().optional(), // 可选 LANGSMITH_TRACING: z.enum(['true', 'false']).default('false').transform(val => val === 'true'), LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'), }); // 解析并验证环境变量 const envParseResult = envSchema.safeParse(process.env); if (!envParseResult.success) { console.error('❌ Invalid environment variables:', envParseResult.error.format()); process.exit(1); // 验证失败，退出应用 } export const env = envParseResult.data;

这样，在你的应用代码中，你就可以从env对象中安全地、带有类型提示地访问配置了：

import { env } from './config'; const llm = new ChatOpenAI({ apiKey: env.OPENAI_API_KEY, model: 'gpt-4', }); if (env.LANGSMITH_TRACING) { // 启用LangSmith追踪 }

这种方式将配置集中管理，提供了运行时验证和完整的TypeScript类型支持，是生产级应用的最佳实践。

5. 可选但推荐的组件：LangSmith集成与调试

当你开始构建复杂的LangChain应用时，调试会变得困难。链条（Chain）的输入输出、工具（Tool）的调用、LLM的请求和响应，这些信息如果只靠console.log，会非常低效。

LangSmith是LangChain官方推出的一个平台，用于追踪、调试和评估LLM应用。它提供了一个可视化的界面，让你可以清晰地看到每一次执行的完整链路，包括每个步骤的输入、输出、耗时、token使用量以及发生的任何错误。

5.1 注册与配置LangSmith

1. 访问 smith.langchain.com 并注册一个账户（通常可以使用GitHub账号）。
2. 在设置页面创建一个API密钥。
3. 在你的.env文件中添加这个密钥：

   LANGSMITH_API_KEY=lsv2_your_actual_langsmith_api_key LANGSMITH_TRACING=true # 启用追踪 LANGSMITH_PROJECT=my-first-langchain-project # 设置项目名，便于在界面中分类查看

4. 安装LangSmith SDK：

   pnpm add @langsmith/langsmith

5. 在你的应用初始化代码中（通常在入口文件的最开始），配置LangSmith。根据官方文档，在LangChain v0.1.x中，通常是通过设置环境变量自动集成的，但为了更明确的控制，可以手动初始化：

   import { Client } from '@langsmith/langsmith'; // 如果环境变量已设置，以下代码是可选的，但显式初始化更清晰 if (process.env.LANGSMITH_API_KEY) { // LangChain内部会自动读取 LANGSMITH_API_KEY 和 LANGSMITH_TRACING 等环境变量 // 你也可以手动创建client，用于更复杂的操作 const client = new Client({ apiKey: process.env.LANGSMITH_API_KEY, }); console.log('LangSmith tracing is enabled.'); }

5.2 在开发中利用LangSmith

配置完成后，运行你的LangChain应用。所有对LLM的调用、链的执行都会被自动记录并发送到LangSmith平台。你可以：

• 查看Trace列表：在LangSmith网页界面，可以看到所有历史执行的概览。
• 深入单个Trace：点击任何一个执行记录，可以看到详细的流程图，展开每个节点查看具体的输入（Prompt）、输出（Response）、使用的模型、消耗的token和耗时。
• 调试与复现：如果某次调用出错了，你可以直接在LangSmith里看到错误堆栈和上下文，甚至可以复制这次调用的确切参数，在本地或Playground中复现问题。
• 比较不同Prompt或模型：通过为不同的运行设置标签（Tags）或元数据（Metadata），你可以横向比较不同配置下的效果和成本。

对于初学者，即使只是运行一些简单的示例，打开LangSmith追踪也能极大地帮助你理解LangChain内部的工作流程，直观地看到你的提示词模板被渲染成什么样子，LLM到底接收到了什么信息。这比任何文字描述都来得有效。

6. 验证环境：创建并运行你的第一个LangChain-ts脚本

理论说了这么多，是时候动手验证一下我们的环境是否真正工作了。我们来创建一个最简单的脚本，使用OpenAI的Chat模型进行一次对话。

6.1 项目结构初始化

首先，确保你的项目结构如下：

my-langchain-project/ ├── .env # 环境变量（已加入.gitignore） ├── .eslintrc.js # ESLint配置 ├── .prettierrc # Prettier配置 ├── .gitignore ├── package.json ├── pnpm-lock.yaml # 或 package-lock.json, yarn.lock ├── tsconfig.json ├── src/ │ ├── config.ts # 环境配置（可选但推荐） │ └── index.ts # 主入口文件 └── dist/ # TypeScript编译输出目录

6.2 编写第一个脚本

在src/index.ts中，写入以下代码：

// 加载环境变量 import * as dotenv from 'dotenv'; dotenv.config(); import { ChatOpenAI } from '@langchain/openai'; import { HumanMessage } from '@langchain/core/messages'; async function main() { // 1. 初始化Chat模型 // 确保你的.env文件中有 OPENAI_API_KEY const chatModel = new ChatOpenAI({ model: 'gpt-3.5-turbo', // 或 'gpt-4' temperature: 0.7, verbose: true, // 在控制台输出详细日志，有助于调试 }); // 2. 构造消息 const messages = [new HumanMessage('用一句话介绍你自己。')]; // 3. 调用模型 console.log('正在调用LLM...'); const response = await chatModel.invoke(messages); // 4. 处理响应 console.log('\n--- AI回复 ---'); console.log(response.content); console.log('--- 结束 ---\n'); // 5. 查看响应元数据（如token使用情况） console.log('响应元数据:', JSON.stringify(response.response_metadata, null, 2)); } main().catch(console.error);

6.3 运行与调试

1. 编译TypeScript：运行pnpm build，这会将src/index.ts编译到dist/index.js。
2. 直接运行Node：node dist/index.js。
3. 使用ts-node进行开发（推荐）：为了在开发时实现更快的热重载循环，我们可以使用ts-node和nodemon。

   pnpm add -D ts-node nodemon

   在package.json中添加开发脚本：

   { "scripts": { "dev": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' src/index.ts" } }

   现在，只需运行pnpm dev，nodemon会监视src目录下的所有.ts文件变化，并自动用ts-node重新执行你的脚本。ts-node会在内存中直接执行TypeScript，省去了手动编译的步骤。

运行脚本后，你应该在控制台看到类似以下的输出：

正在调用LLM... --- AI回复 --- 我是OpenAI开发的AI语言模型，旨在通过理解和生成自然文本来协助用户解决问题、提供信息或进行对话。 --- 结束 --- 响应元数据: { "tokenUsage": { "completionTokens": 28, "promptTokens": 10, "totalTokens": 38 }, "finishReason": "stop", "model_name": "gpt-3.5-turbo-0613" }

看到AI的回复和token使用统计，恭喜你！你的LangChain-ts开发环境已经成功搭建并运行起来了。

实操心得：第一次运行时，如果遇到API key not valid之类的错误，请首先检查：1).env文件是否在项目根目录；2) 变量名OPENAI_API_KEY是否拼写正确；3) API密钥本身是否有效且未过期。如果使用了代理网络，可能还需要配置OPENAI_PROXY环境变量或使用自定义的baseURL参数。调试这类网络问题，开启verbose: true并查看详细的请求日志会非常有帮助。