bug(sdk-js): @langfuse/otel 5.x and 4.x fail to install since OpenTelemetry JS 0.301.0

快速结论：在全新安装 @langfuse/otel 5.x 或 4.x 时，npm 会因 peer 依赖冲突报 ERESOLVE，根源是 OpenTelemetry JS 0.301.0 抬高了 exporter 的 @opentelemetry/api peer 要求。优先排查是否仍在使用 4.x/5.x 旧主版本，并考虑升级到最新 SDK。

适用环境：Issue 已确认：@langfuse/otel 5.14.0 与 4.6.1、@opentelemetry/exporter-trace-otlp-http 0.301.0、Node 25.6.1、npm 11；自托管与 Langfuse Cloud 均可出现，因这是 SDK 安装失败，与服务端无关。Issue 也提到自托管服务端低于 v4.59.0 时 README 建议停留在 v5。

最快修复方案：暂无确认的一步修复方案。Issue 维护者已明确对旧主版本仅提供关键 bug 与安全修复，建议用户升级到最新 SDK；6.x 上同样的安装可正常工作。

注意事项：Issue 中提交者给出了在 5.14.0/4.6.1 上收紧 OTLP exporter peer 上限的补丁对比，并称打过补丁的 5.14.0 可正常安装并通过相关测试，但维护者未确认会发布 5.14.1/4.6.2，因此该补丁只能视为可优先尝试的规避思路，不是官方已验证方案。若服务端低于 v4.59.0，升级前需确认与 v5 的兼容要求。

问题场景

用户在一个新项目中通过 npm 安装 @langfuse/otel 5.x 或 4.x，同时引入 @opentelemetry/sdk-node 0.217 或 @opentelemetry/sdk-trace-node 2，安装阶段即出现依赖树无法解析；该问题与 Langfuse 服务端部署方式无关。

报错原文

bug(sdk-js): @langfuse/otel 5.x and 4.x fail to install since OpenTelemetry JS 0.301.0
npm error ERESOLVE unable to resolve dependency tree
peer @opentelemetry/api@"^1.10.0" from @opentelemetry/exporter-trace-otlp-http@0.301.0

原因分析

最可能的原因是版本约束不匹配。@langfuse/otel 的 5.x 与 4.x 系列仍声明 OTLP exporter peer 范围为 “>=0.202.0 <1.0.0”，而 OpenTelemetry JS 0.301.0 将 exporter 的 @opentelemetry/api peer 提升到 ^1.10.0，同时 @opentelemetry/core 2.x 需要 <1.10.0，两者无法同时满足。6.1.1 中已通过收紧 peer 上限规避该冲突，但修复没有回移到 5.x/4.x。Issue 还提到，在该版本发布前，旧版本虽能安装，但 ESM 导入时会因 SeverityNumber 未导出而崩溃。

环境排查

确认 @langfuse/otel 的实际安装版本是否属于 4.x 或 5.x，可用 @langfuse/otel 6.x 作对照。
确认 @opentelemetry/exporter-trace-otlp-http 是否已到 0.301.0，以及间接引入的 @opentelemetry/api 版本。
确认 Node 与 npm 版本，Issue 报告环境为 Node 25.6.1、npm 11。
确认项目是否使用 ESM 导入；旧版本在安装成功后仍可能有 ESM 导入崩溃风险。
自托管用户需确认 Langfuse 服务端版本，低于 v4.59.0 时 README 建议停留在 v5。

解决步骤

优先评估升级到 @langfuse/otel 最新主版本（6.x）。Issue 中 6.x 的同类安装可正常工作，维护者也建议升级到最新 SDK。
若因服务端版本限制暂时不能升级到 6.x，可优先尝试 Issue 提交者给出的思路：在 5.14.0 或 4.6.1 基础上收紧 OTLP exporter 的 peer 上限，做法与 6.1.1 中已采用的调整一致。注意这是提交者分支上的补丁，尚未被维护者确认发布。
不要仅靠忽略 peer 依赖强行安装旧版本；Issue 指出旧版本即使装上，也可能在 ESM 导入时因 SeverityNumber 未导出而崩溃。
关注 langfuse-js 后续版本是否回移该 peer 上限修复；Issue 中请求发布 5.14.1 与 4.6.2，但维护者仅表示旧主版本只接收关键 bug 与安全修复。

验证方法

在干净目录中重新安装目标版本，确认 npm 不再出现 ERESOLVE 或 peer 依赖冲突。若使用打过补丁的 5.14.0/4.6.1，Issue 提交者称 exporter 0.223.0、api 1.9.1 可正常解析，且 ESM 脚本能向 /api/public/otel/v1/traces 导出 generation；同时可参考其提到的冻装、构建与单元/集成测试结果作为辅助验证，但这些测试结果来自提交者分支，不代表官方版本已通过。