修复 Docker 模块解析错误：LangChain 依赖项调查

日期：2025年8月25日
问题：Docker 容器因 Cannot find module '@langchain/core/prompts.js' 错误而失败
解决方案：LangChain 包间的依赖版本对齐

问题描述

Docker 化的 ChatOllama 应用程序在聊天操作期间遇到关键的模块解析错误：

[nuxt] [request error] [unhandled] [500] Cannot find module '/app/.output/server/node_modules/@langchain/core/prompts.js' 
imported from /app/.output/server/chunks/routes/api/models/index.post.mjs

此错误在多个 API 端点（/api/models/chat、/api/instruction、/api/agents）中持续出现，并阻止应用程序在 Docker 容器中正常运行。

调查过程

1. 初步分析

错误模式：@langchain/core/prompts.js 的 ESM 模块解析失败
环境：Docker 容器构建过程，而非本地开发
受影响文件：从 @langchain/core/prompts 导入的服务器 API 路由

2. 容器检查

调查发现 Docker 容器中缺少导出文件：

/app/.output/server/node_modules/@langchain/core/prompts.js

/app/.output/server/node_modules/@langchain/core/dist/prompts/index.js

3. 版本冲突发现

在依赖树中发现了 三个不同版本 的 @langchain/core：

项目规范：@langchain/core@^0.3.49
实际 Docker 解析：@langchain/core@0.3.72（由 deepagents@0.0.1 引入）
遗留版本：@langchain/core@0.1.54（由较旧的包使用）

关键问题：deepagents@0.0.1 依赖项强制使用 @langchain/core@0.3.72，而项目指定了 ^0.3.49，在 Nuxt 的构建打包过程中创建了版本冲突。

根因分析

核心问题

版本不匹配：较新的 @langchain/core@0.3.72 具有不同的导出结构，与 Nuxt 为 Docker 部署打包模块的方式不兼容。

为什么 Docker 与本地不同？

本地开发：pnpm 的工作区解析优雅地处理了冲突
Docker 构建：Nuxt 的生产打包暴露了版本不一致性
模块解析：不同版本之间的 ESM 导出映射不同

技术细节

// package.json 指定的版本
"@langchain/core": "^0.3.49"

// 但依赖解析拉取了
"deepagents@0.0.1" → "@langchain/core@0.3.72"

// 导致打包期间缺少导出

解决方案：依赖对齐

方法

我们没有选择手动文件补丁，而是通过将所有 LangChain 包更新为兼容版本来选择 正确的依赖管理。

应用的包更新

{
  // 版本对齐的核心更新
  "@langchain/core": "^0.3.49" → "^0.3.72",
  
  // 兼容包更新
  "@langchain/anthropic": "^0.3.19" → "^0.3.26",
  "@langchain/community": "^0.3.41" → "^0.3.53", 
  "@langchain/google-genai": "^0.1.5" → "^0.2.16",
  "@langchain/groq": "^0.0.5" → "^0.2.3",
  "@langchain/ollama": "^0.2.0" → "^0.2.3",
  "@langchain/openai": "^0.5.7" → "^0.6.9",
  
  // 提供商特定更新
  "@langchain/azure-openai": "^0.0.4" → "^0.0.11",
  "@langchain/cohere": "^0.0.6" → "^0.3.4",
  
  // 对等依赖修复
  "ws": "^8.16.0" → "^8.18.0",
  "zod": "^3.23.8" → "^3.24.1"
}

实施步骤

# 2. 重新安装依赖项
pnpm install

pnpm run build

# (server/api/agents/[id].post.ts 中缺少括号)

✓ Built in 17.34s

验证结果

修复前

Docker 错误：模块解析失败
版本冲突：3个不同的 @langchain/core 版本
对等依赖：多个警告
构建状态：在 Docker 中失败

修复后

依赖解析：所有 LangChain 包使用 @langchain/core@0.3.72
本地构建：✅ 成功（pnpm run build）
模块导出：所有包之间一致
对等警告：减少到最小的非关键问题

学到的最佳实践

1. 依赖管理

始终对齐相关包家族的主要依赖版本
对 LangChain 核心等关键依赖使用精确或兼容范围
定期依赖审计 以捕获版本偏移

2. Docker 特定考虑事项

在开发期间在 Docker 中测试构建，而不仅仅是本地
版本冲突在容器化构建中的表现不同 与本地开发
ESM 模块解析 对版本不匹配很敏感

3. 调查方法

首先检查容器 以了解实际文件结构
依赖树分析 以识别版本冲突
标准工具而非手动修复 用于可持续解决方案

开发者技术细节

修改的文件

package.json：更新了 LangChain 包版本
pnpm-lock.yaml：使用一致的解析重新生成
server/api/agents/[id].post.ts：修复了语法错误（缺少括号）

重现命令

docker exec <container> ls -la /app/.output/server/node_modules/@langchain/core/

docker exec <container> find /app/.output/server/node_modules/@langchain/core -name "*prompt*"

npm list @langchain/core

预防策略

// package.json - 对关键依赖项使用更严格的版本范围
{
  "@langchain/core": "~0.3.72",  // 仅限补丁级别的波浪号
  "deepagents": "^0.0.1"         // 确保兼容性
}

结论

这个问题突出了现代 JavaScript 应用程序中 一致依赖管理 的重要性，特别是在通过 Docker 部署时。正确的解决方案涉及将整个 LangChain 生态系统更新为兼容版本，而不是应用手动补丁。

关键要点

版本冲突 在本地和 Docker 环境之间可能表现不同
依赖对齐 对 ESM 模块解析至关重要
标准包管理 始终优于手动文件修复
容器特定测试 应该是开发工作流程的一部分

此修复确保 ChatOllama 的 Docker 部署可靠工作，同时保持标准构建过程并使依赖项与最新的 LangChain 生态系统改进保持同步。