如何在容器构建过程中使用npm ci命令后诊断“not found”这一错误？

test -d node_modules && find node_modules -mindepth 1 -maxdepth 1 | head
test -x node_modules/.bin/vite

通过这些测试，我们可以确认：首先，系统中并没有安装任何包文件；其次，Vite可执行文件确实缺失。需要注意的是，如果省略了某些开发所需的依赖项，也可能会导致类似的错误现象，因此在进行任何配置修改之前，一定要先仔细检查目录内容。

在成功完成安装后，目录列表中应该会显示各个包的名称。执行 `test -x` 命令时不会输出任何内容。在该命令执行后立即检查其退出状态：

echo $?

如果 Vite 可执行文件缺失，预期的退出状态应该是：

1

而退出状态为 0 说明该可执行文件存在且可以正常运行。

重要提示：如果依赖目录为空，那就说明安装过程出现了问题。如果其他包都存在，但只有 Vite 缺失，那么还需要检查是否在安装过程中遗漏了某些开发依赖项。这些命令用于检查依赖目录的内容，而不会修改该目录。

步骤 2：查找锁文件用于下载包的位置

一个典型的锁文件条目结构如下：

{
  "node_modules/example-package": {
    "version": "1.2.3",
    "resolved": "http://packages.internal.invalid/npm/example-package/-/example-package-1.2.3.tgz",
    "integrity": "sha512-<subresource-integrity-value>"
  }
}

上面示例中的 `.invalid` 是一个占位符，实际使用时会替换为真实的内部主机名。这种结构与历史上的锁文件格式是一致的。

根据 npm 的文档说明，`resolved` 字段表示包是从哪个地址获取的。对于从注册库下载的包来说，这个地址可能是一个 tarball 文件的 URL。因此，在构建工具中配置的注册库并不会影响锁文件的生成过程；锁文件已经指明了需要从哪里下载各个包。

我统计了历史记录中受影响的条目数量：在总共 1,038 条依赖项记录中，有 528 条使用了内部主机名，而这些主机名在外部构建环境中是无法解析的。

npm 的调试日志显示，这些问题其实早就在安装过程中出现了。那些无法解析的主机名错误出现在 “Exit handler never called!” 这条错误信息之前，因此这个顺序非常重要：`Exit handler never called!` 这条消息说明了 npm 是如何结束执行的，而那些下载失败的原因则解释了为什么依赖关系树会为空。

我没有只查找某个特定的包名称，而是将所有包含 `resolved` 字段的记录按照主机名进行了分类。以下是一个简单的 JavaScript 脚本，用于实现这一功能：

const fs = require('node:fs')
const lock = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'))
const hosts = {}

for (const entry of Object.values(lock.packages ?? {})) {
  if (!entry.resolved?.startsWith('http')) continue
  const host = new URL(entry.resolved).host
  hosts[host] = (hosts[host] ?? 0) + 1
}

console.table(hosts)

通过这个统计结果可以看出，实际上有 528 条依赖项记录受到了影响，而并不是某个特定的 tarball 文件出了问题。这也让我们明确了修复工作的范围：只需要修改 `resolved` 字段中记录的包下载地址即可，因为包的版本号和完整性校验值并没有发生变化。如果列表中包含了私有注册库的信息，在重新编写相关配置之前，先确定这些注册库为哪些包提供了服务。

历史记录中确实包含这一条信息。该表格使用了示例中提供的替换后的主机名来进行显示：

您的主机名及其对应的URL地址数量取决于您的锁文件内容。此统计结果仅针对HTTP形式的包文件路径，因此其总数可能与依赖项的实际数量有所不同。

注意：请确认哪些无法访问的主机所使用的包来自公共npm注册库，在选择替代前先记录受影响的包的数量。仅凭主机名数量并不能保证重写这些URL地址是安全的。

步骤3：仅重写已知的公共包URL前缀

重新生成锁文件时，修复注册库中的问题与更新依赖项会同时进行。保持包的版本号和完整性值不变，有助于后续审核修复过程。

此示例中受影响的包都来自公共npm注册库。开发平台对这些包进行了代理处理，并保留了它们的完整性值。在容器安装之前，系统会对这些包的URL前缀进行修改。

对于本次操作步骤，请将以下代码保存为rewrite-lockfile.cjs。该脚本只会将那些使用指定前缀的resolved字段进行更新，在写入文件之前还会检查旧版本文件中是否缺少完整性值或存在异常路径。

const fs = require('node:fs')

const oldPrefix = 'http://packages.internal.invalid/npm/'
const newPrefix = 'https://registry.npmjs.org/'
const oldHostname = new URL(oldPrefix).hostname
const filename = 'package-lock.json'
const lock = JSON.parse(fs.readFileSync(filename, 'utf8'))

if (!lock.packages || typeof lock.packages !== 'object') {
  throw new Error('期望的锁文件中应包含packages对象（版本2或3）')
}

let rewritten = 0
for (const entry of Object.values(lock.packages)) {
  if (typeof entry.resolved !== 'string') continue
  if (!entry.resolved.startsWith(oldPrefix)) continue
  if (!entry.integrity) throw new Error('有受影响的包缺少完整性值')
  entry.resolved = newPrefix + entry.resolved.slice(oldPrefix.length)
  rewritten += 1
}

for (const entry of Object.values(lock.packages)) {
  if (typeof entry.resolved !== 'string') continue
  if (!entry.resolved.startsWith('http')) continue
  if (new URL(entry.resolved).hostname === oldHostname) {
    throw new Error('旧主机名的URL前缀仍然不正确')
  }
}

fs.readFileSync(filename, JSON.stringify(lock, null, 2) + '\n')
console.log(`共重写了${rewritten}个URL地址`)

当运行依赖项处理脚本时，实际重写的URL地址数量应与预期值一致。用于测试本教程的小项目产生的结果如下：

共重写了40个URL地址

这个测试项目与实际的应用程序是分开的；实际应用程序中有528个依赖项受到了影响。您可以根据自己的锁文件情况来确认预期的重写数量。对于已经完成修复的文件，其重写后的URL地址数量应为0；如果某个未修复的文件显示重写数量为0，请检查其URL前缀是否正确。

该脚本并不会自动判断某个包是否为公共包，因此需要单独进行确认。npm的完整性检查会验证下载到的文件内容是否与锁文件中的信息一致。