修复 Docker 构建中 npm ci 失败与 Vite 缺失问题

最近，一位开发者在将基于 Node.js 和 Vite 的项目迁移到 Azure Container Registry (ACR) 进行容器化构建时，遇到了一个看似奇怪但极具迷惑性的错误：sh: 1: vite: not found。虽然该应用在浏览器托管的开发环境中运行完美，但在 Docker 镜像构建阶段却彻底崩塌。

故障背景：从开发环境到生产构建的跨越

在构建失败后，开发者 Ahmed Tariq 发现，问题并非出在应用代码或 Vite 配置本身，而是出在依赖管理的环节。该项目的 package-lock.json 是在浏览器托管的开发环境中生成的。在这个环境中，存在一个内部代理服务器，用于访问公共的 npm 包。因此，生成的锁文件中记录的包下载地址指向的是这个内部代理，而非官方的公共 npm 源。

当构建过程在 Azure ACR 中运行时，Docker 构建器无法解析这个内部代理的主机名。虽然 npm ci 命令本身并没有直接报错，而是输出了 Exit handler never called! 并留下了空的 node_modules 目录，但它没有向 Docker 构建系统返回明确的失败状态。这导致后续的构建步骤继续执行，最终在调用 npm run build 时，因为找不到 Vite 可执行文件而报错。

核心原因：npm ci 的严格模式与锁文件污染

要彻底解决这个问题，必须理解 npm ci 在容器构建中的特殊性。

1. 严格的确定性：npm ci 命令专为 CI/CD 环境设计。它会删除现有的 node_modules，并根据 package-lock.json 严格安装依赖。它不会更新锁文件，也不会处理 package.json 中的新依赖。
2. 锁文件中的陷阱：由于开发环境使用了内部代理，package-lock.json 中的 resolved 字段保存了指向该代理的 URL。当 Docker 构建器执行 npm ci 时，它会尝试从这些无效的 URL 下载数百个包的 tarball 文件。
3. 静默失败：由于代理不可达，下载过程会抛出未处理的 Promise 拒绝错误（即 Exit handler never called!），导致 node_modules 目录被清空。因为 npm ci 的失败状态没有被 Docker 正确捕获，下一层构建依然尝试运行，从而暴露出最外层的 vite: not found 错误。

诊断与修复步骤

要解决此类问题，关键在于理解 npm ci 的工作原理以及如何排查锁文件中的无效链接。

1. 检查依赖是否实际安装

在 Docker 构建日志中，首先要确认 node_modules 目录是否为空。如果 npm ci 失败且未安装任何依赖，后续的构建步骤必然会因为缺少二进制文件而失败。这能帮你快速定位问题是否出在依赖层面。

2. 定位锁文件中的无效 URL

使用文本编辑器打开 package-lock.json，检查 resolved 字段。这些字段通常指向一个不存在的内部主机（例如 http://internal-proxy...）。你需要将这些指向内部代理的 URL 前缀，替换为公开的 npm registry 地址（如 https://registry.npmjs.org）。

3. 修复并加固构建流程

在修复了 URL 后，为了防止未来再次发生此类因环境差异导致的构建中断，建议在 Dockerfile 中增加防御性检查。

修改 Dockerfile 示例：

# 假设这是修复 URL 后的安装命令
RUN npm ci --registry=https://registry.npmjs.org

# 增加构建前的校验
RUN ls node_modules/.bin/vite && npm run build

或者更通用的写法：

RUN npm ci && [ -d node_modules/.bin/vite ] && npm run build

4. 验证依赖树与信任边界

修复完成后，必须验证整个依赖树是否完整，并确保没有从不受信任的源引入了错误的包。在 CI/CD 流程中，明确区分开发环境和生产构建环境的包源（Trust Boundary）至关重要。确保锁文件中的 URL 前缀与当前构建环境允许访问的源一致。

总结

通过这个案例，我们可以看到 npm ci 在 Docker 环境中虽然保证了构建的确定性，但也放大了配置错误的影响。遇到 vite: not found 或类似错误时，不要只盯着应用代码，检查 node_modules 是否存在以及 package-lock.json 中的下载地址是否有效，往往是解决问题的捷径。