★ FEATURED ARTICLE 装 Hermes Agent 这件事我前后在两台机器上折腾了差不多一个下午报错界面翻来覆去就那几行但根因完全不同一台卡在 DNS 解析失败另一台是 Node.js 幽灵文件冲突。这两类问题的共同点是报错信息都极其笼统getaddrinfo ENOTFOUND或者command not found看上去像是网络问题或者包没装上实际上排查方向差了十万八千里。这篇记录就是想把这两条坑的完整定位链路写清楚从看到报错的第一秒该敲什么命令到最终怎么改配置、怎么清残留一步一步都是我在现场踩出来的顺序不是事后总结的理想流程。Hermes Agent 这类工具本质上是跑在本地的任务代理框架通过命令行安装、初始化配置、拉起本地服务再对接模型端点执行任务。它比普通 npm 库对环境的敏感度高一个量级因为它安装过程里同时涉及域名解析、二进制依赖下载、全局命令注册、原生模块编译这几件事任何一环断掉最后都表现为一句轻飘飘的安装失败。适合看这篇的人包括第一次部署这类本地 Agent 框架的同学、在受限网络环境里装过东西但总装不干净的同学、以及被明明卸载了重装还是报同样的错折磨过的同学。哪怕你用的是别的 CLI 工具这套排查思路也基本通用。1. 先拆开看一次安装到底动了系统的哪些地方1.1 安装动作背后的四层依赖很多人把装一个 Agent 框架理解成一个原子操作npm i -g敲下去要么成功要么失败。实际在系统层面这一条命令穿透了四层完全独立的依赖每一层的失败模式都不一样。第一层是网络与解析层包管理器要先知道 registry 的域名对应哪个 IP才能建立连接第二层是运行时层也就是 Node 本身的版本、包管理器的版本、全局 bin 目录有没有写进 PATH第三层是原生扩展层很多 Agent 框架会带上 SQLite 绑定、向量检索的原生模块安装时触发 node-gyp 编译需要 Python 和 C 工具链第四层才是应用层包括配置文件生成、端口占用、凭据校验。我后来养成一个习惯装之前先把这四层分别验证一遍能省下大量猜的时间。比如网络层用curl -I打一下 registry运行时层用node -v npm -v确认原生层确认python3 --version和make --version应用层确认目标端口没被占。这套预检看着啰嗦但它是把一次模糊的失败拆成四个明确的是非题值这个时间。1.2 为什么这类框架对环境的容错特别差普通的前端库装不上最多是构建失败重启一下重来就行。Hermes Agent 这类东西麻烦在它会往系统里留下东西全局命令、配置目录、缓存、可能还有后台服务注册。这些东西一旦装了一半残留状态会让后续每一次重装都复现同样的错误而且错误信息指向的位置往往是假象。举个我自己遇到的例子第一次安装在某一步失败了我下意识重跑一遍安装命令结果报错换成了另一个完全不相干的模块找不到。原因是第一次失败时node_modules里已经写了一半的文件第二次安装认为这个包已经存在就跳过了跳过的却是个残缺的目录。这就是为什么后面第 3 节要专门讲幽灵文件——它不是玄学是半成品状态被当成了已完成状态。注意安装中途失败后不要直接重跑同一条命令。先确认有没有.lock文件残留、有没有半截的node_modules清理干净再重来否则你排查的是两个问题叠加后的假象。2. DNS 解析失败先分清到底是哪一段断的2.1 三种长得很像的报错根因完全不同我在两台机器上看到的报错表面都是解析失败但错误码不同处理方式天差地别。把它们分清楚能省掉至少一半的排查时间。错误码字面含义典型根因排查起点ENOTFOUND域名查不到对应记录域名拼写、registry 配错、DNS 服务器不返回该记录手动nslookup该域名EAI_AGAIN临时性解析失败稍后重试DNS 服务器不可达、容器内 resolv 配置失效、并发解析排队超时检查解析器地址连通性ETIMEDOUT连接超时解析成功了但目标端口不通或者拿到的是不可达的地址族检查 IPv4/IPv6 结果顺序ECONNREFUSED连接被拒绝解析没问题是本机服务没起来与应用层配置无关查端口最容易误判的是第三行。ETIMEDOUT很多时候压根不是 DNS 的问题而是域名解析出来了一个 IPv6 地址机器却没有 IPv6 出口于是一路超时到天荒地老。这个坑在 Node.js 环境里格外常见原因我在 2.2 里细说。2.2 分层验证的标准顺序从底往上敲我现在的固定顺序是这样一层通了再上一层不要跳步# 第一层本机到网关通不通 ping -c 2 你的网关地址 # 第二层直接问指定 DNS 服务器绕开系统配置 nslookup registry.npmjs.org 223.5.5.5 dig 223.5.5.5 registry.npmjs.org short # 第三层看系统实际在用哪个解析器 cat /etc/resolv.conf # Linux scutil --dns | head -30 # macOS Get-DnsClientServerAddress -AddressFamily IPv4 # Windows PowerShell # 第四层看 hosts 有没有被改过 cat /etc/hosts这套顺序的价值在于定位断层位置。如果第二层用指定 DNS 能查到但第三层显示系统配的解析器是另一个不可达的地址那问题就在系统配置而不是网络本身。反过来如果第二层就查不到说明是上游 DNS 的问题改本机怎么折腾都没用。这里有个 Node.js 特有的坑必须单独拎出来讲Node 的两套解析 API 行为不一致。dns.lookup()走的是操作系统的getaddrinfo会读 hosts 文件、会走 nsswitch 配置而dns.resolve*()系列走的是内置的 c-ares 库直接向 DNS 服务器发查询完全不读 hosts 文件。这意味着你把域名写进 hosts 之后curl通了、ping通了某个 Node 工具照样报ENOTFOUND因为它内部用的是dns.resolve。我第一次遇到这种情况时以为是 hosts 没生效反复改了三遍才反应过来。还有一个更隐蔽的从 Node 17 开始DNS 结果的返回顺序改成了verbatim也就是不再自动把 IPv4 排到前面而是按解析器返回的原始顺序来。如果目标域名同时有 AAAA 和 A 记录而解析器先返回 AAAANode 就会优先尝试 IPv6。机器没有 IPv6 出口的话你会看到连接卡住十几秒然后超时报错还告诉你解析失败误导性极强。# 验证是不是这个问题强制 IPv4 优先再试一次 NODE_OPTIONS--dns-result-orderipv4first npm i -g hermes-agent # 或者临时导出环境变量 export NODE_OPTIONS--dns-result-orderipv4first这一条命令救过我两次。判断方法也很直接用curl -4和curl -6分别打同一个域名如果-4秒通、-6卡死那基本可以确认是地址族顺序的问题不用再怀疑 DNS 服务器了。2.3 三套修复方案与各自适用场景定位清楚之后修复手段其实就那么几种关键是选对场景。方案一临时环境变量适合一次性安装。就是在命令前面挂NODE_OPTIONS装完就失效不污染系统配置。适合我只是想赶紧把这个包装上的场景也是我验证判断是否正确的首选手段——如果加了环境变量就好了说明判断成立。方案二写 hosts 固定映射适合域名少、IP 相对固定的环境。缺点是 IP 一变就炸而且前面说了对dns.resolve那套 API 无效。所以用之前先确认目标工具用的是哪种解析方式不确定就别把这个当唯一方案。# 先查到 IP再固定写入示例格式 203.0.113.10 registry.npmjs.org方案三改系统解析器配置适合长期在这种环境里工作的机器。Linux 上如果是 systemd-resolved 管理的正确做法是通过resolvectl或修改对应的配置文件而不是直接手改/etc/resolv.conf——因为那个文件很可能是个软链接重启或者在网络状态变化时会被覆盖回去。我见过有人改完发现过一晚上就失效就是踩了这个。注意在容器环境里/etc/resolv.conf通常是运行时挂载进去的容器重启就重置。要让它持久得在容器编排配置层面指定而不是进容器里手改。诊断下来我最常用的组合是先加--dns-result-orderipv4first排除地址族问题再确认系统解析器可达两者都正常还是失败的话才去怀疑上游 DNS 记录本身。这个顺序是从改起来最轻往改起来最重排的避免一上来就动系统配置。3. Node.js 幽灵文件冲突看不见的残留才是元凶3.1 什么叫做幽灵文件这个词是我自己起的指的是那些已经不在包管理器的记录里但仍然存在于文件系统中并且会被执行到的文件。它们的典型特征是你npm uninstall了npm ls -g里也看不到但敲命令的时候它还在跑而且跑的是旧版本。最常见的三种形态全局 bin 目录里的悬空软链接指向一个已经被删掉的包目录执行时报ENOENT或者直接找不到命令多个 Node 版本并存时旧版本安装的全局包留下的可执行文件因为 PATH 顺序问题被优先命中包管理器自带的 shim比如 corepack 生成的启动脚本和你后来手动装的同名命令打架。第二种情况尤其阴险。用版本管理器切换 Node 版本时很多人以为切过去就完事了实际上每个 Node 版本有各自独立的全局包目录。你在 v18 下装的 CLI切到 v20 就消失了反过来如果 PATH 里旧版本的 bin 目录排在前面你明明切到了新版本实际执行的还是旧版本里的那个命令。3.2 三种典型触发场景对照场景表面现象真实原因验证方式系统包与版本管理器并存切换版本后命令行为不变系统级 bin 目录在 PATH 中优先级更高which -a node看是否出现多个卸载不彻底重装后仍报旧版本的错旧 bin 软链接残留指向已删除的目录ls -l看链接目标是否存在多包管理器混用同一个命令两个来源互相覆盖npm 与 pnpm/yarn 的全局目录不同PATH 里都在逐个npm root -g对比我在第二台机器上遇到的就是第一种系统里装了一份 Node后来为了跑另一个项目又用版本管理器装了一份。装 Hermes Agent 的时候npm i -g装到了版本管理器管的那个 Node 下面但 PATH 里系统那份的 bin 目录排在更前面于是执行hermes时命中的是一个更老的、根本不存在这个命令的目录报的是命令找不到。当时我以为是安装失败了实际上安装是成功的只是执行路径错了。3.3 定位方法先搞清楚到底在跑哪一个排查这类问题第一步永远是打印全部候选路径而不是只看第一个。# macOS / Linux列出所有同名命令 which -a node which -a npm type -a hermes # 看当前实际执行的 Node 真实路径注意软链接会被解析 node -p process.execPath node -p process.version # 看 npm 全局安装到了哪里 npm config get prefix npm root -g # Windows PowerShell where.exe node where.exe npm Get-Command node | Select-Object -ExpandProperty Sourcewhich -a和which的区别是这道题的关键前者列出 PATH 里所有命中项后者只给第一个。当你怀疑版本不对的时候只看第一个永远找不到问题因为问题恰恰藏在第二、第三个里面。再补一个很多人不知道的检查点npm config get prefix和process.execPath给出的路径应该属于同一个 Node 安装。如果 prefix 指向的是 A 路径而 execPath 指向 B 路径说明你的 npm 和 node 来自不同安装源全局包装到哪里就是随机事件了。这种错配在装过多个版本管理器的机器上很常见。3.4 清理实操从脏环境回到干净状态定位到问题之后清理步骤我按从轻到重排# 第一步清掉悬空的全局软链接先看再删 ls -l $(npm config get prefix)/bin # 如果某个链接目标不存在可以手动删掉那一个 rm $(npm config get prefix)/bin/hermes # 第二步清 npm 缓存避免装到损坏的 tar 包 npm cache verify # 缓存确实坏了再上强制清理 npm cache clean --force # 第三步清全局包残留目录 npm ls -g --depth0 # 先看清单 npm uninstall -g 包名 # 再逐个卸 # 第四步如果版本管理器管着直接换一个干净的 Node 版本最省事 # 以常见版本管理器为例具体命令按你用的工具来 nvm install 20 --reinstall-packagenpm nvm use 20Windows 上还有两个额外的坑要提。一是同名命令通常有.cmd、.ps1和无后缀三个文件卸载时如果只删了一个剩下的会被 PowerShell 或 cmd 分别命中表现为在终端 A 能用在终端 B 不能用。二是 PowerShell 的执行策略会拦截.ps1脚本现象是命令存在但执行就报错很多人误判成安装失败。还有一个容易忽略的位置node_modules/.bin。项目本地安装时npm 会在这里生成软链接如果包升级后旧链接没清理本地执行会命中旧版本。清理办法就是整个node_modules删掉重装别在里面手动修补。注意删node_modules的时候如果遇到权限错误或者路径过长报错Windows 上优先怀疑路径长度限制把项目挪到靠近根目录的位置再删比装各种工具都管用。4. 完整复现一次从脏环境到跑通的记录4.1 装之前先跑一遍预检这一节把上面所有检查串成一条可执行的流水线。假设你的机器之前装过 Node 相关的东西状态不完全干净那就按这个顺序来。# 1. 环境画像先存档一份出问题好对比 node -v npm -v which -a node which -a npm npm config get prefix echo $PATH | tr : \n # 2. 网络层验证 curl -I -4 https://registry.npmjs.org --max-time 10 node -e require(dns).lookup(registry.npmjs.org,(e,a)console.log(e||a)) node -e require(dns).resolve4(registry.npmjs.org,(e,a)console.log(e||a))第三条和第四条命令是有意分开写的lookup走系统解析器resolve4走 c-ares。两条结果不一致就说明你踩到 2.2 里说的 hosts 不生效那个坑了。这个小技巧我用了很多次比翻日志快得多。预检里我还习惯确认一下目标端口# Linux / macOS lsof -i :3000 # Windows netstat -ano | findstr :3000端口被占的话安装能成功但启动时直接挂掉报错又是一句笼统的服务启动失败。提前查一下省得再绕一圈。4.2 逐步安装每一步都验证真正安装的时候我不再一条命令梭哈而是拆成小步每步验证。慢一点但出错时范围最小。# 第一步只装不触发脚本确认包能下下来 npm i -g hermes-agent --ignore-scripts # 第二步确认命令注册成功且执行的是新装的那个 which -a hermes hermes --version # 第三步再补跑安装脚本原生模块编译在这一步 npm rebuild -g hermes-agent第一步加--ignore-scripts是有讲究的。很多安装失败其实发生在 postinstall 阶段那一步会去下载额外的二进制、编译原生模块、或者初始化配置。先把包本身下下来能把下载问题和脚本执行问题彻底分开。如果第一步就失败那肯定是网络或 registry 的事跟 Node 版本无关如果第一步成功第二步失败方向立刻收窄到脚本和工具链。第二步的验证不能省。hermes --version报出来的版本号要跟你刚装的对得上。对不上就说明命中的是幽灵文件回去做第 3 节的清理。4.3 首次启动与验证装完之后第一次跑我一般会先跑一个带诊断性质的命令多数这类框架都有类似doctor的自检子命令再跑实际业务。# 环境自检 hermes doctor # 初始化配置 hermes init # 前台启动观察日志 hermes start --verbose--verbose这个参数值得每次都加。默认日志只会告诉你启动失败详细日志会告诉你卡在哪个模块、连哪个地址超时。我第一次排查 DNS 问题就是靠详细日志里那行带地址族的连接记录才确认是 IPv6 的问题。启动之后做一次连通性验证# 确认服务真在监听 curl -sS http://127.0.0.1:3000/health这里有个小细节用127.0.0.1而不是localhost。因为localhost本身要走一次解析如果系统解析器有问题连本机都可能连不上白白多一层干扰。同理配置文件里填回调地址、填上游地址的时候能填 IP 就填 IP能省掉后面一堆莫名其妙的超时。5. 速查表与几条踩出来的经验5.1 报错与处置对照表现象最可能原因一条命令验证处置getaddrinfo ENOTFOUND域名解析不到nslookup 目标域名 指定DNS改解析器或写 hostsgetaddrinfo EAI_AGAIN解析器不可达或排队cat /etc/resolv.conf换可达的解析器地址连接卡十几秒后超时IPv6 优先但无出口curl -4与curl -6对比加--dns-result-orderipv4firsthosts 改了但 Node 仍不认内部用的是 c-aresdns.resolve4单独测换方案别死磕 hostshermes: command not found全局 bin 不在 PATHnpm config get prefix把 bin 目录加进 PATH命令在但版本不对PATH 中多个同名命令which -a hermes清理旧版本残留重装仍报同样的错半成品目录被跳过ls node_modules/.bin全删重装只在某个终端里失败PowerShell 执行策略换 cmd 里试同一命令调整执行策略或换 shell5.2 我自己定下的几条规矩装之前先存档环境。node -v、which -a node、npm config get prefix这三条命令的输出我会先复制到一个临时文件里。出问题的时候拿现在的输出一对比哪一项变了立刻就能看出来。这个习惯是从一次装完某个包之后所有全局命令都变了的事故之后养成的那次就是因为版本管理器悄悄换了默认版本。永远先验证再动手。网络问题最常见的错误就是还没确认断在哪就开始改配置。改了三处好了你也不知道是哪一处的功劳改了三处没好你更不知道是哪一处改错了。每次只改一个变量是我唯一坚持的方法论。能用干净环境就别在脏环境里修。版本管理器最大的价值不是切版本是让你能开一个全新的、什么都没装过的 Node 环境。如果排查超过二十分钟还没头绪直接新建一个干净版本重新装比继续修快得多。我现在的止损线就是二十分钟。把诊断命令写成脚本。上面那些检查命令我攒成了一个小脚本下次换机器直接跑一遍输出贴出来就知道什么状态。这不是什么高级技巧但确实把重复劳动压到了最低。最后分享一个我最近才意识到的事这类安装问题的排查成本其实大部分花在报错信息和真实原因之间的翻译上而不是修复本身。ENOTFOUND翻译成人话可能是六种不同的故障command not found可能是四种。真正省时间的做法不是记住所有报错而是记住一两条能把可能性一刀切开的命令——对我来说是which -a和curl -4对-6的对比。这两条命令把我遇到的大部分环境问题都切成了明确的几类剩下的就是按图索骥。
阅读完成 · 觉得有帮助？
