docker-compose up --build 是最直接的重建方式，它强制触发定义了 build 字段的服务镜像重建并启动容器，不依赖旧镜像或缓存；可指定服务名精准重建，如 docker-compose up --build api。
docker-compose up --build 是最直接的重建方式
只要 docker-compose.yml 里某个 service 定义了 build: 字段（比如 build: . 或 build: ./api），执行 docker-compose up --build 就会强制触发该服务的镜像重建，再启动容器。它不依赖本地是否有旧镜像，也不管缓存是否命中——只要加了 --build，就一定走构建流程。
常见错误现象：docker-compose up 后代码没更新，日志还是旧的逻辑。原因就是没加 --build，Compose 直接复用了之前构建好的镜像。
- 开发中改了代码又想快速验证？必须加
--build - 修改了
Dockerfile（比如换了基础镜像、加了新依赖）？必须加--build - 想确保每次都是“干净构建”？配合
--no-cache一起用：docker-compose up --build --no-cache
只重建某一个服务，别全量重来
项目有多个服务（比如 web、api、worker），但你只改了 api 的代码，没必要把三个都重建。Docker Compose 支持按服务名精准重建：
docker-compose up --build api
这个命令只会重建 api 服务对应的镜像，并重启它的容器；其他服务（如 web）保持运行，不中断、不重建。
容易踩的坑：
- 服务名写错（比如写成
apis或API）会导致报错Service 'xxx' not found - 如果该服务之前没构建过，
--build会自动构建；但如果它依赖另一个服务（比如depends_on: [db]），那个依赖服务不会被重建，也不会被重启 - Windows 上 PowerShell 有时会把
-当参数分隔符，建议统一用 CMD 或 WSL 执行
Docker Desktop GUI 里没有“强制重建”按钮
Docker Desktop 的 Dashboard 界面能看到服务状态、日志、端口，但**不提供一键重建镜像的功能**。点 “Restart” 只是重启容器，不会重新 build；点 “Recreate” 也只是基于现有镜像新建容器，不是 rebuild。
所以如果你习惯用 GUI 操作，得切到 Terminal 标签页手动敲命令。Dashboard 本质是个观察面板，不是构建控制台。
替代方案（仅限调试）：
- 在 Docker Desktop 的 Terminal 中直接运行
docker-compose up --build -d - 右键服务 → “Open in Integrated Terminal”，自动 cd 到 compose 文件所在目录
- 不要依赖 GUI 做构建决策，尤其生产环境配置变更时，命令行才是唯一可信路径
build 缓存让重建变快，但也可能掩盖问题
Docker 默认启用 layer 缓存：如果 Dockerfile 前几行（比如 COPY package.json .、RUN npm ci）没变，就会复用之前构建好的 layer，跳过安装依赖步骤。这能显著提速，但也会导致一个问题：你删了 package.json 里的某个包，却没清缓存，结果那个包还在镜像里。
判断是否真重建了？看终端输出有没有类似这样的行：
Step 4/10 : RUN npm ci --only=production ---> Using cache ---> 7a2b3c4d5e6f
出现 Using cache 就说明没重跑这步。要绕过它，有两个选择：
-
--no-cache：彻底禁用所有 layer 缓存，适合 CI 或确认行为一致性时用 - 局部失效：比如在
RUN npm ci前加一行RUN echo $BUILD_TIME > /dev/null并每次传不同BUILD_TIME构建参数，强制某一层失效
真正麻烦的是多阶段构建中 builder 阶段的缓存污染——它不显示在最终镜像里，但会影响中间层判断。这种时候，--no-cache 是最省心的兜底方案。
