企业官网建设流程全解析

LangChain.js 全解析：Agent 工程平台的安装、多环境支持、Monorepo 架构与本地开发实践

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs

本文以 langchainjs 仓库根目录的 README.md 为核心骨架，系统讲解 LangChain.js 作为"Agent 工程平台"的定位与安装方式，并结合仓库源码深入剖析其 pnpm workspaces + Turborepo 的 Monorepo 结构、langchain与@langchain/core两个核心包的双模块导出机制、Node/Edge/浏览器多运行环境的验证体系，以及 examples 与本地开发的完整工作流。读完本篇，你可以独立安装并使用 LangChain.js、按需在 Node.js、Cloudflare Workers、Vercel、Deno、Bun 等环境中部署，并能直接进入仓库参与开发与集成测试。

1. LangChain.js 是什么：定位与核心能力

根 README.md 将 LangChain.js 定位为"The agent engineering platform"（Agent 工程平台），并对其核心定义如下：

LangChain is a framework for building LLM-powered applications. It helps you chain together interoperable components and third-party integrations to simplify AI application development — all while future-proofing decisions as the underlying technology evolves.

即 LangChain 是一个用于构建 LLM 驱动应用的框架，通过可互操作的组件与第三方集成，把 LLM 应用开发简化为"链式组合"，并在底层技术演进时保护你的技术决策。

README 明确给出的六大使用场景（见 README.md）：

• 实时数据增强（Real-time data augmentation）：通过覆盖模型提供商、工具、向量库、检索器的庞大集成库，把 LLM 连接到多样的数据源与内外部系统。
• 模型互操作（Model interoperability）：在抽象层之上自由替换模型，随行业前沿演进快速适配而不丢失既有工程积累。
• 快速原型（Rapid prototyping）：模块化、组件化的架构让你可以快速构建并迭代 LLM 应用，无需从零重建即可测试不同方案与工作流。
• 生产就绪（Production-ready features）：内置对监控、评估、调试的支持（通过 LangSmith 等集成），并沉淀了经过实战验证的模式与最佳实践。
• 活跃的社区与生态：丰富的集成、模板与社区贡献组件，持续跟进 AI 最新进展。
• 灵活的抽象层级：从快速上手的高层 chain 到细粒度控制的基础组件，抽象层级随应用复杂度增长而调整。

1.1 快速安装

README 的 Quick Install 一节（README.md）支持 npm、pnpm、yarn 三种包管理器，命令如下，可直接复制使用：

npm install -S langchain # 或 pnpm install langchain # 或 yarn add langchain

从各核心包的 package.json 可以看到，langchain与@langchain/core均声明"engines": { "node": ">=20" }，即在 Node.js 环境中最低要求 Node 20。

2. Monorepo 架构：pnpm workspaces + Turborepo

langchainjs 是一个大型 Monorepo。根 package.json 中声明了"packageManager": "pnpm@10.14.0"，并通过 pnpm-workspace.yaml 定义了工作区范围：

packages: - "libs/*" - "libs/providers/*" - "examples" - "internal/*"

这对应仓库中四大类目录：

构建编排由 Turborepo 完成。根 turbo.json 定义了任务依赖图，关键任务包括：

• build:compile：依赖上游包的^build:compile（先构建依赖方），输入为src/**、tsconfig.json、tsdown.config.ts、package.json，输出dist/**；
• test：依赖build:compile，输入包含src/**、tests/**、**/*.test.ts、vitest.config.ts；
• test:int/test:integration/test:standard:int：不启用缓存（"cache": false），面向需要外部 API 凭据的集成测试。

根 package.json 的 scripts 展示了常用入口：

pnpm build # turbo build:compile，全仓库增量构建 pnpm test:unit # 各包单元测试（排除 test-exports-* 与 examples） pnpm test:exports:docker # docker compose 运行环境导出测试 pnpm test:ranges:docker # 依赖版本区间测试（lowest/latest） pnpm lint / pnpm format:check # oxlint 与 oxfmt 检查 pnpm release # changeset publish

值得注意的是，根 package.json 还维护了一份pnpm.overrides列表（如undici、esbuild、sharp等大量版本下限），用于锁定传递依赖的安全版本，体现大型集成框架对依赖面管理的重视。

2.1 核心包langchain与@langchain/core的分工

• @langchain/core（libs/langchain-core/package.json，当前仓库内版本 1.2.10）：核心抽象与 schema 层，提供 base classes、runnables、messages、prompts、tools、tracers 等。其exports字段暴露了 60 余个子路径（如./runnables、./messages、./prompts、./output_parsers、./tracers/langsmith相关能力），意味着下游可以只按需引入子模块。
• langchain（libs/langchain/package.json，当前仓库内版本 1.5.11）：主包，@langchain/core是其 peerDependency；运行时依赖@langchain/langgraph（^1.4.13）、@langchain/langgraph-checkpoint与langsmith。

从源码结构看，主包的入口 libs/langchain/src/index.ts 的再导出清单勾勒出当前版本的 API 重心：

• 消息基类：BaseMessage、AIMessage、SystemMessage、HumanMessage、ToolMessage等（来自@langchain/core/messages）；
• 统一聊天模型工厂：initChatModel（来自./chat_models/universal.js）——一个字符串/配置驱动的模型入口；
• 工具原语：tool、HeadlessTool、StructuredTool、DynamicTool等；
• Agent 能力：整模块再导出./agents/index.js与./agents/middleware/index.js（createAgent及其预置中间件）。

这说明当前langchain主包已围绕Agent（createAgent + 中间件）而非传统 chain 组织核心 API，与 README 中"agent engineering platform"的定位一致；传统的 chains/memory 等经典 API 保留在@langchain/classic（libs/langchain-classic）中供存量项目使用。

2.2 双模块导出：ESM / CJS / 浏览器三条件

libs/langchain/package.json 的exports是理解"同一份源码如何服务多环境"的关键。以主入口为例：

".": { "browser": "./dist/browser.js", "input": "./src/index.ts", "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }, "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } }

• browser条件指向独立的浏览器构建（对应 libs/langchain/src/browser.ts），供 Webpack/Vite/浏览器直连场景使用；
• require/import分别给出 CJS（.cjs+.d.cts）与 ESM（.js+.d.ts）产物，由 tsdown 一次性产出；
• input条件指向src/*.ts，供本工作区内的源码级引用（配合 internal/tsconfig 与 tsdown 的 input 支持）。

langchain包还额外导出./browser、./chat_models/universal、./hub、./load、./storage/in_memory、./storage/file_system、./tools等子路径，@langchain/core的子路径导出更多（见 libs/langchain-core/package.json 的 exports 段）。这种细粒度子路径 + 模块条件设计，正是 README 中"Flexible abstraction layers"承诺的落地形式。

另外，两个核心包对 schema 库的依赖均写成"zod": "^3.25.76 || ^4"，即同时兼容 zod v3 与 v4——仓库中专门设有 environment_tests/test-zod-compat 目录（zod-v3 / zod-v4 / zod-mismatch 三组用例）验证该承诺。

3. 支持环境与多运行时验证体系

README 的 Supported Environments 一节（README.md）声明 LangChain.js 用 TypeScript 编写，可在以下环境运行：

• Node.js（ESM 和 CommonJS）—— 20.x、22.x、24.x
• Cloudflare Workers
• Vercel / Next.js（Browser、Serverless 与 Edge 函数）
• Supabase Edge Functions
• Browser（浏览器）
• Deno（仓库根目录提供 deno.json 作为 Deno 入口配置）
• Bun

这些声明不是口头承诺，仓库内置了两套自动化验证体系。

3.1 环境测试：environment_tests

environment_tests/README.md 说明：环境测试通过隔离的 Docker 容器模拟真实用户环境，确保包在不同模块系统（ESM、CJS）、不同打包器（esbuild、Vite、Webpack via Next.js）、不同运行时（Node.js、Bun、Cloudflare Workers）与 TypeScript 编译下的正确性。测试矩阵覆盖：

其执行方式与 README 一致：

docker compose -f environment_tests/docker-compose.yml run <environment> # 例如： docker compose -f environment_tests/docker-compose.yml run test-exports-esbuild

执行链路为：environment_tests/scripts/docker-entrypoint.sh 启动 → 由 environment_tests/scripts/test-runner.ts 在容器内/app建立沙箱 → 复制测试包与本地 workspace 包 → 对不可用的包将workspace:*依赖替换为已发布版本 →pnpm install --prod后运行 build/test。其核心保证是"针对真实发布的包做安装测试，而非源码测试"。对应根命令即pnpm test:exports:docker（package.json）。

3.2 依赖区间测试：dependency_range_tests

dependency_range_tests/docker-compose.yml 配合 dependency_range_tests/scripts/langchain/test-with-lowest-deps.sh 与 test-with-latest-deps.sh，分别在"最低依赖版本"与"最新依赖版本"下验证langchain及各标准提供商包（anthropic、cohere、google-vertexai、openai）的安装与运行。该机制支撑zod ^3.25.76 || ^4、langsmith >=0.5.0 <1.0.0这类宽版本区间声明的可靠性，对应根命令pnpm test:ranges:docker。

3.3 标准测试与模型画像工具

internal/目录承载跨包工程能力：

• internal/standard-tests：定义提供商包应遵守的标准单元/集成测试套件，pnpm test:standard在根目录统一调度；
• internal/model-profiles：模型画像的 CLI 与生成器（src/cli.ts、src/generator.ts），配合各提供商目录下的profiles.toml文件（如 libs/providers/langchain-openai/profiles.toml）为模型提供结构化画像；
• internal/tsconfig：全仓库共享的 TypeScript 基线配置。

4. 官方示例集：从 Agent 到多智能体

examples/是独立 workspace 包（examples/package.json），依赖了几乎全部第一方提供商与大量第三方集成（ChromaDB、Pinecone、Milvus、MongoDB、Redis、pgvector 等）。运行方式：

pnpm start # tsx 直接执行 src/index.ts（自动加载 .env） pnpm start:dist # 先 tsc 编译再运行产物

示例组织（examples/src/）：

• createAgent/：当前主推的 Agent 开发范式，含tools.ts、structuredOutput.ts、streaming.ts、supervisor.ts等，以及middleware/子目录下的预置中间件演示（hitl.ts、summarization.ts、promptCaching.ts、modelCallLimit.ts、llmToolSelector.ts等）和dynamicTools/（simple.ts、advanced.ts）；
• multi-agent/：handoffs、路由、子代理编排（handoffs-customer-support.ts、router-knowledge-base.ts、subagents-personal-assistant.ts等）；
• llms/、extraction/：模型直连与结构化抽取（如 OpenAI tool-calling 抽取示例 examples/src/extraction/openai_tool_calling_extraction.ts）；
• langchain-classic/：chains、memory、retrievers、vectorstores 等经典模块的完整示例库，供沿用旧 API 的读者参考。

5. 生态版图与包选择策略

README 的生态清单（README.md）与仓库结构相互印证：

• Deep Agents（JS）：构建在 LangChain 之上的更高层包，面向具备规划（planning）、子代理（subagents）、文件系统等能力的 Agent，是 README 中面向初学者的推荐入口；
• LangGraph：低层 Agent 编排框架，提供可定制架构、长期记忆与 human-in-the-loop 工作流。本仓库中langchain主包直接依赖@langchain/langgraph与@langchain/langgraph-checkpoint（见 libs/langchain/package.json 的 dependencies 段），即 createAgent 的底层运行时即 LangGraph；需要更深的状态图编排时，应直接面向 LangGraph 编程；
• LangSmith：构建、测试、监控 LLM 应用的开发者平台；langchain与@langchain/core均依赖langsmithSDK，仓库内 tracers 与 standard-tests 也围绕该观测体系组织；
• Integrations：即libs/providers/下的第一方集成矩阵。从 pnpm-workspace.yaml 的libs/providers/*与目录清单看，当前涵盖 openai、anthropic、google（genai/vertexai/vertexai-web/gauth/webauth/common）、aws、azure 系（cloudflare）、cohere、deepseek、groq、mistralai、ollama、xai、openrouter、perplexity、fireworks、together-ai、ibm，以及向量/检索/记忆类集成（pinecone、qdrant、weaviate、pgvector、mongodb、redis、neo4j、exa、tavily、ibm 等）。

选型建议（以当前仓库为准）：

1. 新项目 Agent 开发 →langchain主包的createAgent+middleware（示例见examples/src/createAgent/）；
2. 只写模型与工具层 → 直接用@langchain/core+ 具体提供商包（如@langchain/openai），保持依赖最小；
3. 维护存量 chains/memory 代码 →@langchain/classic（libs/langchain-classic）；
4. 接入 MCP 服务器工具 →@langchain/mcp-adapters（libs/langchain-mcp-adapters 自带 SSE/streamable HTTP 示例）；
5. 文本切分 →@langchain/textsplitters（已拆分为独立包）。

6. 本地开发工作流

结合根 package.json 与 CONTRIBUTING.md（仓库不再接受新集成进入本仓库，新集成须作为独立 npm 包发布），在仓库内参与开发的标准流程为：

1. 环境准备：要求 Node v24.x（node -v确认），建议通过 nvm 切换（nvm use）；
2. 安装依赖：pnpm install；
3. 先构建核心包（其他包依赖其产物）：pnpm --filter @langchain/core build；
4. 常用任务（均可在根目录通过pnpm --filter <package>定向执行）：

pnpm --filter langchain build # 构建主包（tsdown） pnpm --filter langchain test # 单元测试 + 类型测试（*.test.ts / .test-d.ts） pnpm --filter langchain test:integration # 集成测试（需 .env 中的 API 凭据） pnpm lint && pnpm format:check # oxlint / oxfmt 检查

测试文件约定：单元测试命名*.test.ts，集成测试命名*.int.test.ts（需外部 API 凭据，通常建议用pnpm --filter <package> test:single逐个运行），类型测试命名.test-d.ts并使用 vitest 的expectTypeOf断言。

CI 侧的完整验证由根脚本串联：pnpm test=test:unit+test:exports:docker；另有test:standard（standard 套件）与test:ranges:docker（依赖区间）两条 Docker 化流水线。

7. 小结

回到 README.md 的主线：LangChain.js 以"可互操作组件 + 第三方集成"为核心设计，当前仓库内langchain（1.5.11）与@langchain/core（1.2.10）围绕 Agent（createAgent + 中间件）组织 API，底层由 LangGraph 提供运行时；通过 exports 多条件构建与environment_tests的八环境 Docker 矩阵、dependency_range_tests的版本区间矩阵，兑现了对 Node 20/22/24、Cloudflare Workers、Vercel/Next.js、浏览器、Deno、Bun 的多环境支持承诺；配合 examples 示例集、changesets 发布流程与 oxlint/oxfmt/vitest 工具链，构成一个可直接安装使用、也可深入参与开发的完整 TypeScript Monorepo。

版本说明：文中包版本、Node 要求、zod 兼容区间均取自当前仓库各 package.json，随仓库演进可能变化，请以仓库实际文件为准。

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs