如果你最近打开过 Hacker News大概会注意到一个挺扎眼的问题Is observability over the dependencies in codebases still a problem翻译过来就是代码库中依赖的可观测性今天还依然是个问题吗。放在两三年前大家的答案可能是“这是个工程素养问题”到了 2025 年这句话依然值得认真回答。先说我的判断依赖可观测性不是被解决了而是从“没工具”变成了“工具很多、但没有系统串联”。lockfile 让你看不到版本如何漂移npm audit 只能看到已知漏洞APM 只能告诉你某个接口慢却很难告诉你慢是因为一个间接依赖在某个冷门操作里做了一次同步 IO。依赖图对大多数人来说仍然是一团只能靠猜的黑盒。这篇文章我会从问题本身出发把它拆成几个可观测性维度然后给出一条相对完整的工具链和实操路径从npm explain/npm why这类入门命令到pnpm approve-builds处理构建脚本再到dependency-cruiser做依赖结构规则、osv-scanner做已知漏洞扫描最后落到 OpenTelemetry 的运行时观测。建议收藏因为其中很多命令你在真实项目里一定用得上。1. 这个问题在 2025 年为什么还没有消失先看几个真实出现过的场景你就知道这个问题没有消失。第一个场景某天 CI 突然红了代码没有任何提交lock 文件也一个字节没改只是因为某个传递依赖在父包声明的版本允许区间内发了一个小版本。你打开npm why层层追查才发现一个你从未主动安装的包被三个不同依赖以不同版本引入。第二个场景安全团队转发了一个高危 CVE你花了一下午用npm ls反向排查到底哪些上游服务引用了这个包结果因为依赖被提升到根目录代码里 import 的路径和你预想完全不同。第三个场景线上订单模块偶发超时APM 显示 HTTP 层一切正常但某个第三方 SDK 在内部会定期执行一次慢操作而你根本没有办法从业务 trace 里看到这次慢操作。三个场景分别代表三件事依赖版本漂移不可见、依赖来源路径不可见、依赖运行时行为不可见。它们都不是“代码逻辑写错了”而是“代码之外的东西”发生了变化。恰恰是这些代码之外的东西决定了你的系统今天能不能跑、跑得稳不稳。所以 Hacker News 上那个问题——代码库中依赖的可观测性仍然是个问题吗——看起来像是反问。答案很明显仍然是。而且更准确地说真正缺失的不是某一个工具而是贯穿静态依赖树、包管理器行为、安全审计、运行时调用链的一整套观察能力。很多团队已经在单点工具上做了不少工作但始终没有把“依赖”当成一个需要长期观测的工程对象来治理。2. 依赖可观测性到底在观察什么要想不把“依赖可观测性”理解成一个口号最好先把它拆成五个子问题子问题要回答的内容典型工具或命令有什么项目的直接依赖和全量传递依赖清单npm ls --all、cargo tree谁引入某个依赖的引用路径是直接声明还是被传递带入npm why、pnpm why为什么存在这个依赖服务什么功能体积多大有没有更优选择bundle 分析、依赖审查当前状态是否过期、是否包含已知漏洞、许可证是否合规npm outdated、npm audit、osv-scanner运行表现依赖是否被实际调用调用频率、错误率、延迟如何OpenTelemetry、APM、依赖专项监控这五个问题合起来才是完整的依赖可观测性。注意大多数团队只做到了第一层和第二层也就是“至少知道项目里有哪些包”。从第三层开始信息断层会越来越严重。一个更直观的类比是城市交通。你不可能只知道自己城市的车辆清单你还需要知道车辆从哪里出发、往哪里去、是否有违规记录、是否超速、路上有没有事故。代码库里的依赖也是如此。单纯知道 node_modules 里有多少个包没有任何意义关键是谁在什么情况下把什么包带进来这个包在当前项目里到底做了什么以及它出了问题之后你多久能定位到它。这里我可以把概念收敛一下依赖可观测性不是对依赖“是否存在”的记录而是对依赖“从引入到运行”全路径的理解能力。它同时包含静态可观测性和动态可观测性。静态部分来自包管理器和依赖图谱动态部分来自运行时指标、链路追踪和日志。两者没有打通之前我们得到的都是局部视图。3. 为什么 lockfile 解决不了依赖可观测性很多人会问不是有 package-lock.json、yarn.lock、pnpm-lock.yaml 吗只要锁住版本问题不就解决了吗这个想法对了一半。lockfile 是一种强大的可控性工具而不是观测工具。它记录的是某一次依赖解析的结果是一个瞬间快照。它可以让你在npm ci时得到和上次一致的 node_modules但它不能回答“这个包是谁在哪个 PR 里引入的”“它的许可证是否允许商用”“它未来一个小版本是否安全”这类需要持续观察才能回答的问题。更麻烦的是语义化版本的假设。semver 认为 minor 和 patch 版本不应该破坏兼容性但现实中的 API 破坏经常发生在 minor 版本里。lockfile 能保证的是这次安装和上次一致但它不能保证下一次解析时新生成的 lockfile 一定安全。这就是为什么很多 CI 事故都发生在有人重新生成 lock 文件之后。还有一个被长期忽略的点依赖的构建脚本。很多依赖在安装时会执行 postinstall 脚本这些脚本会下载二进制、打补丁、写文件。普通依赖扫描根本看不到这些脚本做了什么。也就是说一个依赖对项目的影响并不只在它暴露的 API 里还藏在安装阶段的隐藏行为中。这属于典型的“不可观测区域”。系统级依赖也是一样。一个基于 Electron 的应用可能依赖系统里某个版本的 libnss3一个深度学习项目可能依赖特定版本的 CUDA 动态库。这些依赖在 lockfile 之外在 npm audit 之外却在运行时真真切切影响你的应用。因为它们的可见度更低遇错时排查路径也更长。所以结论很明确lockfile 是控制依赖的手段不是观察依赖的手段。两者之间差着一整套工程能力。4. 工具生态现状从命令行到全链路过去几年依赖可观测性工具其实已经多了不少只是它们散落在不同环节很少有人把它们串成一条完整的链路。4.1 先从包管理器自带的命令开始绝大多数排查场景其实用包管理器原生命令就够了。在 npm 里npm ls --all可以查看完整依赖树npm explain或npm why可以回答“这个包为什么存在”。在 pnpm 里对应的是pnpm why在 yarn 里是yarn why。Python 项目可以用pipdeptreeGo 项目可以用go mod graphRust 项目可以用cargo tree。这些命令没有花哨界面却是定位依赖来源的第一手段。4.2 依赖构建脚本pnpm approve-builds 是一个重要变化依赖的可观测性不仅包括“这个包存在”还包括“这个包在安装时做了什么”。较新版本的 pnpm 对依赖生命周期脚本变得更保守默认不会运行未列入白名单的依赖构建脚本。如果某个依赖需要在安装阶段执行脚本比如 esbuild、sharp、electron 这类二进制型依赖就可能出现类似ERR_PNPM_IGNORED_BUILDS或者“Ignored build scripts”的提示。此时 pnpm 会明确要求你运行pnpm approve-builds自己选择允许哪些依赖执行构建脚本。这个机制的价值在于它把“安装时执行任意脚本”这件事从隐式变成了显式。过去 npm 安装依赖时任何依赖的 postinstall 脚本都会静默执行你很难知道到底发生了什么。现在至少在一个环节上工具替你建立了一道审计门。4.3 已知漏洞扫描安全层面的观测同样不可缺失。npm audit可以扫描已知漏洞GitHub Dependabot 会在发现漏洞时自动提交更新 PRGoogle 的开源项目osv-scanner则把多个漏洞数据库合并起来能够扫描 lockfile 和多种语言生态。Snyk 这类商业工具则把漏洞、许可证、依赖关系整合在一套平台里。它们的共同价值是把“安全风险”变成可量化的状态数据。4.4 依赖图与结构规则除了安全依赖之间的结构问题也需要可观测性。dependency-cruiser是一个非常好用的依赖图分析工具可以检查循环依赖、孤儿依赖、越层依赖。它不只是一个可视化工具更是一个能够作为 CI 门禁的规则引擎。当代码库越来越复杂时人工 review 依赖结构已经不可靠必须交给规则自动判断。4.5 运行时观测依赖在运行时并不是真正的黑盒前提是你把依赖调用纳入到观测体系里。OpenTelemetry 是目前最主流的可观测性标准通过自动插桩和手动埋点你可以看到一次完整的请求经过哪些组件调用链在哪里变慢哪个第三方 SDK 抛出了异常。不过要注意不是所有第三方依赖都会自动被插桩很多 SDK 需要你手动为它建立 span。这也是运行时依赖观测里真正难的部分。5. 实操把依赖可观测性落到一个小项目里这一节我们用一个小项目跑通上面提到的工具链。项目本身很简单重点在于你能够在自己项目里复制同样的操作。5.1 准备示例项目先创建一个目录初始化一个 npm 项目然后安装几个常见依赖。这里用chalk、express和lodash作为演示目标它们都是非常常见的包方便观察依赖树和传递依赖。mkdir dep-observability-demo cd dep-observability-demo npm init -y npm install chalk5 express4 lodash4 npm install -D dependency-cruiser opentelemetry/api opentelemetry/sdk-node opentelemetry/auto-instrumentations-node opentelemetry/exporter-trace-otlp-http安装完成后先看全量依赖树。5.2 查看全量依赖树npm ls --all会输出从根节点开始的完整依赖树。不要被输出长度吓到这一层最重要的作用是让你在宏观上看到项目到底承载了多少依赖。npm ls --all输出会很长但注意一点如果你看到一个包在输出里出现了多次说明它被多个父依赖引用而且可能以多个版本存在。这在 npm 的扁平化 node_modules 里非常常见但从逻辑依赖树上看它就是一个需要重点观察的信号。5.3 精确回答“这个包是从哪来的”当你想知道某个具体的包为什么会被安装用npm explain或npm why。npm why lodash输出大致会告诉你lodash 是你直接声明的依赖同时可能被 express 内部某个包依赖。这种信息对定位“为什么会有两个 lodash 版本”非常重要。在 pnpm 项目里对应的命令是pnpm why它同样会展示依赖链路径。如果你的项目已经迁移到 pnpm遇到依赖问题时不要只盯着npm lspnpm why给出的路径信息更符合 pnpm 的目录结构。5.4 处理 pnpm 场景下的构建脚本如果你在 pnpm 项目里安装了electron、esbuild、sharp这类需要在安装阶段执行构建脚本的依赖安装时可能会看到类似这样的提示Ignored build scripts: esbuild. Run pnpm approve-builds to pick which dependencies should be allowed to run.或者在某些版本下直接报ERR_PNPM_IGNORED_BUILDS。这是 pnpm 为了安全而做的限制不会默认执行所有依赖的 lifecycle 脚本。你需要运行pnpm approve-builds命令会进入交互模式列出被忽略构建脚本的依赖由你选择是否允许执行。这里我的建议是只批准你确认可信、且确实需要构建脚本的依赖不要全部放行。把 npm 时代的“所有依赖安装时都可以随便执行脚本”变成“每个依赖都需要单独审批”本身就是一种可观测性的提升。5.5 用 dependency-cruiser 检查依赖结构依赖树中容易出现两类结构问题循环依赖和没有来源的孤儿依赖。它们不会直接让安装失败却会在代码变更时制造难以预料的连带影响。用dependency-cruiser可以在项目里建立一条可重复执行的结构检查规则。先创建一个配置文件.dependency-cruiser.cjsmodule.exports { forbidden: [ { name: no-circular, severity: error, from: {}, to: { circular: true } }, { name: no-orphans, severity: warn, from: {}, to: { orphan: true } } ], options: { doNotFollow: { path: node_modules } } };然后运行npx depcruise --config .dependency-cruiser.cjs src --output-type text这里的配置文件声明了两条规则项目里不允许出现循环依赖不允许出现没有被任何模块引用的孤儿模块。循环依赖意味着模块之间的加载顺序和依赖关系会变得难以预测孤儿模块意味着代码在没有被引用的情况下被冗余打包。把这样的规则放到 CI 里每次提交都能自动暴露问题。5.6 用 osv-scanner 扫描已知漏洞npm audit覆盖的是 npm 生态的漏洞数据而osv-scanner的优势在于跨生态。它能够扫描 lockfile 里记录的全部依赖版本并与多个公开漏洞数据库比对。安装方式很简单go install github.com/google/osv-scanner/v2/cmd/osv-scannerlatest如果你的机器没有 Go 环境也可以用 Docker 镜像来运行。扫描当前项目osv-scanner scan .或者直接指定 lockfileosv-scanner scan package-lock.json输出会列出存在已知漏洞的依赖包、漏洞编号和修复建议。在判断是否合入一个依赖升级时把osv-scanner的结果作为质量门禁是相当有效的做法。5.7 运行时依赖观测用最小的 OpenTelemetry 示例依赖的静态状态可以扫描依赖在运行时的行为则需要通过链路追踪来观测。下面用一个最小示例展示思路。先写一个初始化脚本instrument.jsconst { NodeSDK } require(opentelemetry/sdk-node); const { getNodeAutoInstrumentations } require(opentelemetry/auto-instrumentations-node); const { OTLPTraceExporter } require(opentelemetry/exporter-trace-otlp-http); const sdk new NodeSDK({ traceExporter: new OTLPTraceExporter({ url: http://localhost:4318/v1/traces }), instrumentations: [getNodeAutoInstrumentations()] }); sdk.start();在你的应用入口执行node --require ./instrument.js app.js这样 Node.js 应用就会把所有自动插桩组件产生的 trace 发送到本地 OTLP Collector。如果某个第三方 SDK 没有被自动插桩也可以在业务代码里手动创建 spanconst api require(opentelemetry/api); const tracer api.trace.getTracer(demo); function fetchUser(id) { const span tracer.startSpan(thirdPartySdk.fetchUser); try { return thirdPartySdk.getUser(id); } catch (err) { span.recordException(err); span.setStatus({ code: api.SpanStatusCode.ERROR }); throw err; } finally { span.end(); } }这样做的价值在于当第三方 SDK 抛错时这个错误不再只是控制台里的一行堆栈而是被记录到完整的链路中。你可以看到它发生在哪个请求上下文里、上游和下游是谁、错误到底来自哪一次第三方调用。6. 怎样判断“依赖可观测性已经到位”做完上面的实操后你可以用下面几组问题来评估自己的项目到底处在哪个阶段。第一当有人问“这个项目一共有哪些依赖为什么会有这些依赖”时团队能不能快速回答。如果能说明静态依赖树观测已经及格。第二当某个依赖发布了新版本团队能不能在一天之内评估升级影响范围。如果能说明版本漂移观测已经建立了流程。第三当收到安全漏洞通告时团队能不能在半小时内确定当前项目是否受到影响影响的路径是什么。如果能说明安全观测已经和依赖图谱打通。第四当线上某个第三方 SDK 出现慢调用或异常时trace 里能不能直接看到这个调用点及其上下文。如果能说明运行时观测已经覆盖到了依赖边界。大多数团队离这个状态还有一定距离。这不一定是工具的问题更多是意识问题——我们花了大量精力观测应用自己的代码却很少把依赖当成一等公民纳入观测体系。7. 不同生态里那些经典的依赖崩溃现场依赖可观测性问题并不只在 npm 生态出现。下面是几个很常见的真实现象它们共同说明一点依赖问题长期存在只是每一种生态暴露问题的形式不同。问题现象所属生态根因与可观测性的关系pnpm install 报ERR_PNPM_IGNORED_BUILDSNode.js / pnpm依赖的构建脚本未被批准执行安装阶段脚本行为不可见component mscomct2.ocx or one of its dependencies not correctly registeredWindows缺少 VB6 组件注册或依赖的 OCX 未注册系统级组件没有清单化libzbar-64.dll (or one of its dependencies)报错Windows / Linuxzbar 动态库的依赖链缺失VC 运行库不在原生库依赖无法被常规依赖管理覆盖The following packages have unmet dependencies: awesun: 依赖: libc6 ( 2.27...)Debian / Ubuntu系统包版本过低不满足依赖声明apt 依赖解析信息机械缺少可读上下文error: failed dependencies: epel-release 7 is needed by remi-release-7.9-6CentOS / RHELrpm 包依赖特定版本系统扩展包系统源依赖版本约束无法自动修复拿第一个例子来说pnpm approve-builds就是为了把安装阶段隐藏的脚本行为显性化。如果不经过这一步一个依赖即使安装成功它内部执行的下载、编译、写环境变量等动作都对开发者完全透明。第二个和第三个例子都属于 Windows 和原生二进制依赖。很多人以为依赖问题只有 package.json 层面的版本冲突实际上不少历史遗留系统会直接依赖 OCX、DLL 这类系统组件。缺少可观测性的结果是应用在开发机上能跑在用户机器上莫名其妙报错错误信息提到的那个“one of its dependencies”成了一个永远无法确定的谜。第四个和第五个例子是 Linux 系统包依赖的典型场景。apt 和 rpm 虽然会明确告诉你依赖不满足但它的输出信息对排查来说远远不够你需要自己去查 glibc 版本、检查源配置、确认包仓库是否匹配。这类问题的难点不在于修复命令本身而在于你无法快速获得一份“当前系统依赖全貌”。需要提醒的是涉及系统级依赖变更时务必在测试环境验证做好备份遵循最小权限原则不要在生产环境盲目执行强制安装命令。8. 把依赖可观测性做成工程日常依赖可观测性不是一次性的治理项目而应该成为日常开发流程的一部分。下面这几条建议基本可以在团队里直接落地。第一条把依赖变更当作 code review 的一等对象。凡是修改package.json、锁文件或依赖清单文件的 PR都要像改业务代码一样认真审查。审查时至少回答三个问题这个依赖提供的能力是什么是否真的需要直接依赖有没有更轻量或维护更活跃的替代方案。第二条在 CI 中引入四道检查。第一道是锁文件完整性检查用npm ci或pnpm install --frozen-lockfile确保 CI 环境没有静默生成新锁文件。第二道是安全扫描把npm audit或osv-scanner的严重级别设成门禁。第三道是依赖结构规则用dependency-cruiser挡住循环依赖和越层依赖。第四道是依赖变更审查可以用 GitHub 的dependency-review-action或者自建脚本确保一个 PR 不会无解释地引入大量新依赖。name: dependency-checks on: pull_request: jobs: check-deps: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm audit --audit-levelhigh - run: npx depcruise --config .dependency-cruiser.cjs src上面的 workflow 是一个模板action 版本建议以官方仓库当前推荐为准。重点不是模板本身而是让依赖检查成为每次提交的必经环节而不是等到发布之前才想起来做。第三条给依赖升级建立独立节奏。不要在一个业务 PR 里顺手升十几个依赖那样出了问题根本定位不了。建议团队每个月安排一次专门的依赖升级周期先查看npm outdated或pnpm outdated再按依赖重要程度分批次升级。每次升级都单独出锁文件变更方便回滚。第四条重要项目建立运行时依赖告警。对关键第三方 SDK 的调用打点检测错误率和延迟指标。当某个 SDK 出现异常时能在 APM 告警中直接看到依赖名称和调用点。这样依赖问题就不会再变成“某个服务莫名变慢”的玄学问题。第五条维护一份DEPENDENCIES.md。不要把它写得像流水账而是记录那些引入后容易出问题的关键依赖说明为什么引入、当前版本策略、升级注意事项。这样即使换人维护也不会丢失依赖层面的上下文。9. 一个值得立刻做的动作如果今天只做一件事我建议你先把package.json和锁文件变更纳入 code review 的一等审核对象并至少在 CI 里加上npm audit和dependency-cruiser两道门禁。工具可以慢慢补但视角必须从现在开始改变。依赖可观测性确实是一场持久战但它的收益也很直接构建失败时你能更快定位根源安全通告时你能更快响应线上依赖异常时你不再只能靠重启和回滚解决问题。从 Hacker News 上的那个提问到今天文章里完整跑通的命令链中间差的其实就是这套工程意识。希望这篇文章里的命令和思路能在你真实项目里派上用场。