pnpm run dev:web fails with “Module not found: Can’t resolve ‘@langfuse/shared'” when using Turbopack

问题场景

在 Langfuse 仓库根目录执行 pnpm run dev:web 启动仅 Web 的开发服务器时，Turbopack 立即崩溃，报模块找不到错误，涉及 @langfuse/shared 及其子路径导入。完整复现步骤为：克隆仓库 → pnpm install → 复制 .env.dev.example 为 .env 并填写变量 → 执行 pnpm run dev:web → 访问 http://localhost:3000。

报错原文

⨯ Module not found: Can't resolve '@langfuse/shared'
⨯ Module not found: Can't resolve '@langfuse/shared/src/server'
⨯ Module not found: Can't resolve '@langfuse/shared/src/db'
Import map: aliased to relative './packages/shared/src' inside of [project]/web

原因分析

根本原因在 next.config.mjs 的 turbopack.resolveAlias 配置，包含两个问题：

1. 相对路径错误：别名指向 "./packages/shared/src"，但该路径会以 Next.js 的工作目录 web 为基准解析，实际变成不存在的 web/packages/shared/src，正确应为 "../packages/shared/src"。

2. 缺少子路径映射：大量代码通过 @langfuse/shared/src/server、@langfuse/shared/src/db 等子路径导入。没有为 @langfuse/shared/src 设置显式别名时，Turbopack 会把后缀拼接到已错误的路径上，导致解析失败。

此外，维护者明确说明需要先构建 shared 包（生成 packages/shared/dist）；若删除 dist，@langfuse/ee 会直接加载 dist 文件夹内容而不受 resolveAlias 影响，因此仍会报 Can't resolve '@langfuse/shared/encryption'。

环境排查

• 确认操作系统为 Ubuntu 26.04，Node.js 24，pnpm 11.4.0。
• 确认 Next.js 版本为 16.2.6，Langfuge 版本为 v3.185.0（self-hosted）。
• 确认 Git 提交为 main 分支 f248d8c73（2026 年 6 月 25 日）。
• 确认已执行 pnpm install 并复制 .env.dev.example 到 .env。
• 检查 packages/shared/dist 是否存在且为最新构建产物。
• 检查 next.config.mjs 中 turbopack.resolveAlias 的当前配置值。

解决步骤

1. 先构建 shared 包（如 pnpm --filter @langfuse/shared build 或项目文档指定的构建命令），确保 packages/shared/dist 存在。
2. 打开 next.config.mjs，定位 turbopack 配置块中的 resolveAlias。
3. 将 @langfuse/shared 的别名路径从 "./packages/shared/src" 改为 "../packages/shared/src"（注意相对路径以 web 目录为基准）。
4. 新增一条子路径映射："@langfuse/shared/src": "../packages/shared/src"，与上一条并列。
5. 保存配置后重启 pnpm run dev:web。

可优先尝试的完整配置如下（Issue 中提供的建议）：

turbopack: {
  resolveAlias: {
    "@langfuse/shared/src": "../packages/shared/src",
    "@langfuse/shared": "../packages/shared/src",
  },
},

验证方法

重启后在浏览器打开 http://localhost:3000，确认页面正常加载且控制台不再出现 Module not found: Can't resolve '@langfuse/shared' 等错误。进一步验证热更新行为：编辑 packages/shared/src 下的任一文件，确认浏览器无需手动重建即可即时刷新，这是修复别名路径后的预期效果。

参考来源

langfuse/langfuse #14542