Docker构建镜像时Sending context阶段速度极慢如何优化？

该阶段耗时和构建上下文的总文件数量强相关，和文件总大小关联极弱。node_modules目录通常包含几万到几十万个小文件，每个文件在上下文传输时都需要单独遍历、计算哈希、同步权限/元数据，在跨进程传输、尤其是colima这类虚拟机场景下还要经过虚拟化文件传输层，小文件IO开销会被进一步放大，就会出现总大小仅几十MB但传输耗时十几二十分钟的现象。

方案1：在镜像内安装依赖，从构建上下文中排除宿主机node_modules（推荐，适配绝大多数场景） #

“容器运行需要依赖所以不能排除node_modules”是常见认知偏差：容器运行所需的依赖完全可以在Docker构建流程内安装，不需要传输宿主机的node_modules——且宿主机安装的依赖往往和容器内的操作系统、Node版本、CPU架构不兼容（比如Mac端arm架构安装的二进制依赖放到x86容器内直接无法运行，colima做架构转译时这类问题更频发）。
操作步骤：

• 在项目根目录创建.dockerignore文件，将node_modules及其他构建无关路径排除：

node_modules
.git
npm-debug.log
*.local
dist
build
test
docs

• 调整Dockerfile，利用Docker分层缓存机制安装依赖，避免重复安装：

FROM node:20-alpine
WORKDIR /app
# 先拷贝依赖清单文件，该层仅当依赖清单变更时才会重新执行
COPY package*.json ./
# 容器内安装匹配运行环境的依赖，--omit=dev可按需排除开发依赖
RUN npm ci
# 拷贝剩余项目源码
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

调整后，占总文件数90%以上的node_modules不会被纳入构建上下文，Sending context阶段耗时通常可以降到数秒，同时镜像内依赖的兼容性、构建缓存复用率都会明显提升。

方案2：特殊场景必须使用宿主机node_modules时，开启上下文压缩 #

如果受离线环境、预编译二进制依赖等限制，确实需要将宿主机node_modules传入构建上下文，可以开启Docker的上下文压缩功能，将大量小文件打包为单个压缩流后再传输，大幅降低小文件元数据同步的开销：

• 直接使用docker build命令时，添加--compress参数：

docker build --compress -t node-app .

• 使用docker-compose构建时，在build配置段开启压缩（兼容docker-compose v2及以上版本）：

services:
  app:
    build:
      context: .
      compress: true

该方案在colima这类虚拟化场景下，对大量小文件的传输速度通常有5-10倍的提升。

方案3：colima环境专项优化 #

Mac端使用colima作为虚拟化引擎时，两项调整可以进一步降低传输开销：

• 给colima虚拟机分配足够的计算资源，避免资源不足导致的IO等待：

colima start --cpu 4 --memory 8 --disk 60

• 不要将项目放在宿主机与colima的共享挂载目录下构建，将项目代码放到colima虚拟机本地磁盘后再执行构建，可规避9p/osxfs共享文件系统的小文件遍历性能缺陷。

方案4：精简构建上下文范围 #

即使不排除node_modules，也可以通过精简上下文内无关文件减少总文件数：

• 完善.dockerignore配置，将所有构建、运行不需要的文件（文档、测试用例、本地配置、git仓库文件、临时缓存文件等）全部排除
• 对必须传入的大量零散静态文件，可提前打包为单个压缩包，在Dockerfile内执行解压，减少上下文内的小文件数量

注意：不要默认将整个项目目录作为构建上下文，只要上下文内小文件数量过万，哪怕总大小不足100MB，传输耗时也会出现明显上涨。

内容的提问来源于stack exchange，提问作者erKito