AI 编出来的包名装不上：幽灵依赖的识别顺序与供应链风险

2026-07-28

数据截至 2026-07，各产品的额度与报错口径以官方最新说明为准。

一个装不上的包名，绝大多数人归因到了环境上：换镜像、清缓存、升级包管理器、怀疑公司代理。真正的成因往往在更前面一层——那个包名从来没有在任何 registry 上存在过，是模型顺着命名习惯拼出来的。你在环境层折腾多久都不会成功，因为要装的东西不存在。更麻烦的是第二种情况：名字确实存在，但存在的原因是有人提前把这类常被编造的名字注册了。这时候安装会成功，问题从”跑不起来”变成”跑起来了，而且引进了一个你没审过的第三方代码”。

这篇只处理包名、模块名、函数名这一类幻觉，因为它有一个别的幻觉不具备的性质：可以机器验证，答案是二值的。站内大模型幻觉是怎么产生的讲的是幻觉的成因和总体判断，如何核查 AI 的回答给的是通用核查流程，模型别名带来的风险说的是模型标识本身的混乱；本篇只做一件它们不做的事——把”标识符幻觉”拆成可执行的排查顺序，并说清它为什么会顺着包管理器变成供应链问题。

一、先分因：三种现象长得像，成因完全不同

看到红色报错就动手改环境，是排查里最贵的习惯。先花两分钟把现象归类，后面能省掉一小时。

现象 A：安装阶段就失败，registry 明确说没有这个名字。 这是最干净的一种，说明名字是拼出来的。模型编包名不是随机的，它有很强的规律：把常见前缀和常见后缀重组（某个库叫 xxx-core，它就敢写 xxx-utils）、把另一门语言里的库名平移过来、把某个类的名字直接当成包名、把 GitHub 上某个仓库的 README 标题当作发布名。这些拼法都符合命名直觉，所以读代码的时候一点都不刺眼。

现象 B：包装上了，但导入之后找不到那个函数或那个参数。 这时候名字是真的，行为是编的。常见两个变体：一是这个函数在更早或更晚的版本里存在，现在装的版本没有；二是这个函数从来不存在，模型按 API 风格补齐了一个”应该有”的方法。第二种更危险，因为你会先怀疑自己版本装错了，去一个个试版本，试到最后才发现整条调用链是虚构的。

现象 C：安装报的是网络、超时或证书类错误。 ETIMEDOUT、ECONNRESET、或者自签证书导致的证书链校验失败——这些和名字真伪无关，是你和 registry 之间的链路问题。把 C 误判成 A，你会去改代码；把 A 误判成 C，你会去改代理。两个方向都白干。

判别顺序就是 C → A → B：先确认链路通，再确认名字在，最后确认 API 在。反过来做一定绕远路。

二、判别表：现象、成因、验证、动作

现象	大概率成因	怎么验证	处置动作
安装失败，registry 返回 404	名字不存在，是拼出来的	`curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/<name>` 或换 `https://pypi.org/pypi/<name>/json`	用标准库或真实存在的库重写这段；不要试相近拼法
装上了，导入后报找不到该属性或方法	包真、API 假，或版本错位	`python -c "import pkg; print([n for n in dir(pkg) if 'key' in n])"` 看实际导出	按已安装版本的实际接口改调用；确认某版本真有该接口再锁版本
装上了，但这个包在官方文档、issue、常见教程里都找不到出处	抢注：有人注册了模型爱编的名字	`npm view <name> time.created maintainers repository` 看元数据，再取 `https://api.npmjs.org/downloads/point/last-week/<name>` 看周下载量	立即停用并清缓存，按凭据可能已泄露处理
本地能装，CI 里装不上	本地全局环境或缓存里有残留，锁文件没进版本库	干净容器里跑 `npm ci` 或 `pip install -r requirements.txt`	提交锁文件；本地删掉依赖目录复现一遍
内部私有包名在公网也能解析到	依赖混淆：命名空间没被保护	查 `.npmrc` 里 scope 的 registry 路由，再查公网同名是否存在	私有包统一加 scope 并强绑私有源，拒绝回落公网
报 TLS 证书链校验失败或 ETIMEDOUT	链路问题，与名字无关	`curl -v` 直接访问同一个 URL 对比	先修网络与证书信任，再重新判定名字
函数名能在 issue、博客里搜到，已安装版本的导出里没有	未合并的改动、fork、或别的语言里的同名物	clone 上游仓库后 `git log -S '<symbol>' --oneline` 搜符号出现历史	以已发布版本为准；需要就自己实现，不要按未发布接口写

表里的两条 curl 是这套排查的地基：HTTP 200 表示这个名字在公共源上确实存在；404 表示公共源上没有——它可能是模型编的，也可能只是你自己的私有包或工作区包，下一节会把这两种情况分开；5xx 或超时说明你在看的是链路问题，而不是名字问题。三种结果对应三条完全不同的路，不要混着看。

三、按顺序做动作

第一步，把可疑标识符全列出来，而不是只看报错那一行。 报错只会停在第一个失败的地方。AI 一次写出的一段代码，编造往往是成串的：一个不存在的包，配着三个不存在的方法，再配一个不存在的配置项。只修报错那行，剩下的会在后续运行时一个个再炸。

第二步，对每个包名跑存在性检查，输出布尔结果。 不要人工肉眼判断，也不要问模型”这个包存在吗”——它会很自然地确认自己编的东西。写个几行的循环把依赖清单里的名字过一遍 HTTP 码，比读十遍代码可靠。跑之前先手动打一个你确定存在的包，拿到 200 再开跑——否则链路不通的时候整片结果都是超时或 5xx，很容易被读成”这些名字全是编的”，方向立刻反过来：

# npm 侧：把 dependencies 的名字逐个换成状态码
node -p "Object.keys(require('./package.json').dependencies||{}).join('\n')" \
| while read -r p; do
    printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/$p")" "$p"
  done

# Python 侧：先剥掉注释和版本约束，只留包名
grep -vE '^[[:space:]]*(#|$)' requirements.txt | sed -E 's/[<>=!~;].*//' | tr -d ' ' \
| while read -r p; do
    printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/$p/json")" "$p"
  done

读结果有一个必须知道的例外：404 不等于”一定是模型编的”。私有包、公司内网源上的包、monorepo 里的工作区包，在公共 registry 上本来就查不到，一样返回 404。所以这一步真正要做的是分成三堆——公共源上存在、你自己认得的内部包、既不在公共源上你也说不出它从哪来。第三堆才是幻觉嫌疑，而它同时也是依赖混淆最容易下手的地方。

第三步，对存在的包做”这个包是不是我以为的那个”检查。 重点看四项：创建时间、维护者、仓库地址是否可达且与包名对得上、近期下载量。注意下载量不在 npm view 返回的元数据里，要单独取 downloads 接口。一个刚创建、没有可达仓库、下载量近乎为零、却恰好叫着一个非常顺口名字的包，风险画像已经很完整了。

第四步，把结论落到锁文件和 CI 上。 排查的产物不该只是”我改好了”，而应该是一条能拦住下一次的机制：锁文件进版本库、CI 用 npm ci 这类严格按锁文件安装的方式、私有 scope 绑死私有源。把这一步做掉，同类问题就不会第二次进主干。这属于工程化改造，和 AI 代码评审工具怎么用里讲的门禁思路是一套。

第五步，兜底：允许放弃这个库。 如果这段功能本来就是二十行标准库能干的事，AI 引一个包只是它的表达习惯，直接自己写掉，比继续找”到底哪个库有这个函数”更快。

四、为什么这同时是供应链安全问题

把编造包名只当成”AI 写错了”，会漏掉真正要命的那一半。

编造不是随机的，它是可预测的。同一类需求、同一种命名风格，不同人问不同模型，得到的假包名会高度重合。这意味着攻击面是稳定的：有人只要收集这些高频假名字，提前在公共 registry 上注册，就能坐等安装量自己送上门。整个过程不需要入侵任何系统，不需要钓鱼，也不需要绕过任何审批——是你的开发者主动 npm install 的，是你的 CI 主动拉的。

一旦装上，能拿到的东西远超一个业务库该有的权限：安装脚本可以在构建机上执行、构建机上通常有仓库凭据和发布凭据、环境变量里往往躺着密钥。所以这类事件的处置基线是按凭据泄露走，而不是按”删掉包”走：轮换该环境里所有可能被读到的密钥，检查这段时间的对外请求，检查有没有以你名义发出的提交或发布。密钥的分层与轮换见 API 密钥安全管理。

还有一条更隐蔽的路径：依赖混淆。你的内部包叫什么名字，本来是”公司内部信息”，但它会顺着 AI 工具的上下文、错误日志、公开仓库的配置文件泄出去。一旦有人在公网注册了同名包，而你的解析顺序会回落到公网，安装就可能拿到外面那个。防这个不靠人的警惕，靠配置：私有包统一加 scope，scope 在配置里死死绑到私有源，禁止回落。

技术债的角度也一样要算。为了让一段虚构的调用跑起来而引进来的包、为了对齐虚构接口而写的适配层，都会长期留在代码里，且没人记得它当初为什么在。这笔债会记在后面接手的人头上。

顺带说一句关于工具选择：部分海外 AI 编程工具的官方服务对中国大陆有区域限制，不支持直连使用；市面上存在一些第三方中转，但来源与合规性无法核实，这里不推荐也不背书。这不是本篇的重点，只是提醒——如果你的依赖来源本身就绕了一圈不明链路，前面所有的名字校验价值都会打折。

五、什么情况下别再折腾

排查最贵的不是做错方向，是不肯止损。给几条硬线。

试到第三个包名就停。 如果你已经在换第二、第三个”看起来更对”的相近名字，说明你在陪模型继续编。停下来退回需求层：这段功能到底要做什么，标准库或已经在依赖里的库能不能做。

版本试到第二个就停。 为了找到”哪个版本有这个函数”而挨个装版本，是典型的沉没成本陷阱。正确做法是打开已安装版本的实际导出看一眼，或者在仓库里搜这个符号的出现历史。搜不到，就是没有过。

发现抢注嫌疑，立刻不再做技术排查，改走安全流程。 这时候继续研究”这个包到底能不能用”没有意义，也不安全。断网、保留现场、轮换凭据，然后再谈。

回滚点定在依赖清单变更的那次提交。 不要手工往回删依赖，容易漏。用版本控制回到依赖文件和锁文件都干净的那一版，再把确认过的改动重新加上去。

换条路的判断依据只有一个：这段功能的核心价值在不在这个库上。 在（比如它是某个协议实现、某个厂商 SDK），值得花时间找到真实的那个库。不在（工具函数、字符串处理、日期格式化），自己写掉，五分钟结束。

六、避坑清单

坑一：问模型”这个包存在吗”来验证。 为什么会踩——这是最省事的动作，而且它一定会给你一个确定的答复。怎么避——存在性只认 registry 的 HTTP 响应码，把这条写成脚本或写进检查清单，不给自己留手工判断的空间。

坑二：把安装失败一律当成镜像或代理问题。 为什么会踩——国内开发环境里确实有很大比例的安装失败是源和网络导致的，经验会把你直接带到那个方向。怎么避——先看报错语义分类：404 和证书链校验失败是两码事，超时和”没有匹配版本”也是两码事。分类之后再动手。

坑三：只改报错那一行。 为什么会踩——报错停在第一处，修完就能往下跑一段，有强烈的进展感。怎么避——一次性把这段代码里所有外部标识符列出来批量核，把成串的编造一次清完。

坑四：本地能装就认为没事。 为什么会踩——本地环境有缓存、有全局装过的包、有历史遗留目录，会让不存在的东西”看起来能用”。怎么避——干净容器里按锁文件重装一遍作为唯一验收标准。

坑五：内部包名和公网包名重名而不设边界。 为什么会踩——起名时只考虑内部好记，没考虑公共命名空间会不会被别人抢。怎么避——私有包一律加 scope，scope 绑私有源，并禁止解析回落。

坑六：把处置停在”卸载了那个包”。 为什么会踩——错误消失了，看着就像修好了。怎么避——只要安装脚本在你的机器上执行过，就按凭据可能已泄露处理，轮换密钥并核对这段时间的异常请求。

坑七：锁文件不进版本库，或者 CI 用宽松安装。 为什么会踩——图省事，或者觉得锁文件冲突麻烦。怎么避——锁文件必须提交，冲突时按依赖变更重新生成而不是手改；CI 用严格按锁文件安装的命令，让”某人本地装了个奇怪的包”没法悄悄传播。

坑八：把这套检查只做一次。 为什么会踩——排查完有解脱感，没人愿意再看第二遍。怎么避——把存在性检查放进提交前钩子或流水线的一个步骤，成本是几秒钟，收益是这类问题再也不用人来发现。

收束

标识符幻觉之所以值得单独拎出来说，是因为它在所有幻觉里最好治：不需要判断力，不需要领域知识，一个 HTTP 状态码就能定性。真正的难点在于人会本能地把它归因到环境，然后在错误的层面上花掉一整个下午；而在最坏的情况下，它会安静地成功，把一个没人审过的第三方包送进你的构建机。

一份可以贴到评审模板里的自检清单：

这次改动新增的每个外部包名，是否都跑过 registry 存在性检查，留下了 200 或 404 的结果？
新增依赖的创建时间、维护者、可达仓库地址，是否都对得上？
报错到底属于名字不存在、接口不存在，还是链路问题，分类结论写下来了吗？
锁文件是否随这次改动一起提交，CI 是否严格按锁文件安装？
私有包是否都在受保护的命名空间下，且不会回落到公网源？
如果确认装过可疑包，这台机器上能读到的密钥是否已经轮换？

把这六条固化成流程，AI 写多少个不存在的 import 都不再是事故，只是一次几秒钟的红灯。