如何在容器构建中 npm ci 之后诊断 vite: not found
内容提要
文章讲述Node.js项目迁移到Azure容器构建后报“vite: not found”。根因是package-lock.json中528个依赖的resolved字段指向仅开发环境可访问的内部代理主机，npm ci下载失败却未使构建中断。修复方法是仅重写这些公共包URL前缀为npm官方源，保留版本与完整性值，并在每次独立安装后检查Vite可执行文件，分阶段构建验证。
延伸解读
锁文件中的 resolved 字段是构建可移植性的关键
文章指出，package-lock.json 中每个依赖的 resolved 字段记录了 npm 实际下载 tarball 的地址。当项目从浏览器开发环境迁移到 Azure 容器构建时，这些地址仍指向仅内网可访问的代理主机，导致 npm ci 下载失败。即使构建环境配置了正确的 registry，npm 仍会优先使用锁文件中的 resolved 地址。因此，在跨环境构建前，应检查锁文件中 resolved 字段的主机名是否在目标环境可达。
npm ci 失败可能不中断 Docker 构建，需显式检查安装结果
文章中的事故里，npm ci 因下载失败打印了“Exit handler never called!”并留下空的 node_modules，但该失败状态没有阻止后续 Docker 层执行，直到 npm run build 才报出“vite: not found”。这说明不能依赖 npm ci 的退出码来保证依赖已安装。应在依赖安装后立即检查 node_modules 是否非空以及关键可执行文件（如 vite）是否存在，让构建在安装阶段就失败，避免误导性的后续错误。
重写 URL 前缀而非重新生成锁文件，可保留版本与完整性
文章建议仅将已知公共包在 resolved 字段中的旧主机前缀替换为 npm 官方源，而不重新生成整个锁文件。这样做可以避免无意中升级依赖版本，同时保留 integrity 值供 npm 校验下载内容。重写脚本应只处理匹配指定前缀的条目，并检查替换后旧主机名是否完全消失。重写后需对比版本和 integrity 字段，确保依赖身份未变。此方法仅适用于确认来自公共 npm 源的包，私有包需保留在可达的私有 registry。
每个独立安装点都需应用相同的防护措施
文章强调，CI 工作流中的安装与容器构建中的 npm ci 是相互独立的。修复了工作流中的安装，并不会自动修复 Dockerfile 内的安装。因此，URL 重写和安装后检查应放在每个独立安装步骤之前，包括 CI 类型检查安装、容器构建安装以及多阶段 Dockerfile 中的运行时安装。否则可能出现类型检查通过而镜像构建仍失败的情况，掩盖真正问题。
Q&A
容器构建时 npm ci 之后报 vite: not found，可能是什么原因？
根因可能是 package-lock.json 中的 resolved 字段指向了仅开发环境可访问的内部代理主机，导致 npm ci 下载依赖失败，但构建未中断，后续执行 npm run build 时找不到 Vite 可执行文件。
如何检查 npm ci 是否真的安装了依赖？
在失败的环境中运行 `test -d node_modules && find node_modules -mindepth 1 -maxdepth 1 | head` 查看 node_modules 是否为空，再用 `test -x node_modules/.bin/vite` 检查 Vite 可执行文件是否存在，并通过 `echo $?` 查看退出状态（1 表示缺失）。
怎样找出 package-lock.json 中哪些依赖的下载地址有问题？
可以编写脚本解析 package-lock.json，遍历 packages 对象，提取所有以 http 开头的 resolved 字段，按主机名分组统计。例如使用 Node.js 脚本输出每个主机名对应的 URL 数量，从而定位不可达的主机。
修复 package-lock.json 时如何只改 URL 而不影响版本和完整性？
使用脚本仅替换 resolved 字段中已知的公共包 URL 前缀（如从内部代理地址改为 https://registry.npmjs.org/），保留 version 和 integrity 值不变。脚本应检查受影响包是否具有 integrity 值，并确保旧主机名不再出现。
修改 Dockerfile 时如何确保依赖安装阶段失败能及时暴露？
在依赖安装阶段（npm ci 之后）添加检查命令 `test -x node_modules/.bin/vite`，如果 Vite 可执行文件不存在则立即失败。同时使用 `--include=dev` 显式安装开发依赖，并将依赖安装与源码构建分为两个阶段。
这种 URL 重写方法适用于所有情况吗？有哪些风险？
仅适用于公共 npm 包通过透明代理的情况。如果包来自私有仓库、有补丁或同一版本下字节不同，重写可能导致安全问题。应确保 integrity 值不变，并验证重写前后版本和完整性一致，否则应保留私有仓库并配置认证。
