docker multi-stage 构建中中间层未复用的根本原因是构建上下文或依赖文件变动导致缓存失效；同一 stage 内 layer 可复用的前提是所有前置指令完全一致，包括文件内容、命令字符串及格式。
为什么 Docker build 时 multi-stage 的中间层没被复用
根本原因不是 stage 写法不对，而是构建上下文或依赖文件变动触发了缓存失效。Docker 不会跨 stage 复用 layer，但同一 stage 内的 layer 可以复用——前提是前面所有指令完全一致（包括 copy 的文件内容、RUN 命令字符串、甚至空格和换行）。
-
COPY requirements.txt .后紧跟RUN pip install -r requirements.txt是安全的；但如果中间插了RUN echo "hi"，后续所有 layer 都会失效 - 只要
requirements.txt文件内容变了，哪怕只多一个空行，pip install这一层就无法复用 - 使用
.dockerignore排除__pycache__/、*.pyc、venv/等，否则COPY . .会让每次构建都因时间戳不同而跳过缓存
python 缓存构建中 COPY 的顺序为什么必须是「先依赖后代码」
因为 Docker 缓存基于指令逐行比对，一旦某条 COPY 或 RUN 命令的输入变了，它及之后的所有 layer 全部失效。Python 项目里，requirements.txt 变动频率远低于源码，所以要把低频变更的文件提前 COPY。
- 错误写法：
COPY . .→RUN pip install -r requirements.txt：每次改一行app.py都会导致重装全部依赖 - 正确写法：
COPY requirements.txt .→RUN pip install -r requirements.txt→COPY . .：只有requirements.txt改了才重装 - 如果用了
poetry或pipenv，对应要COPY pyproject.toml poetry.lock或Pipfile Pipfile.lock，而不是只拷pyproject.toml
multi-stage 中如何让 builder stage 的 Python 包在 final stage 复用
不能靠“复制整个 site-packages 目录”来省事，那会破坏隔离性且极易出错。正确做法是利用 builder stage 编译/安装，再精确复制输出产物（如 wheel、可执行脚本、或编译后的 .so），而非依赖路径。
- builder stage 里用
RUN pip wheel --no-deps --wheel-dir /wheels -r requirements.txt生成 wheel - final stage 用
COPY --from=builder /wheels /wheels+RUN pip install --no-deps --find-links /wheels --trusted-host localhost /wheels/*.whl - 避免
COPY --from=builder /usr/local/lib/python3.x/site-packages /usr/local/lib/python3.x/site-packages：版本不匹配、C extension ABI 不兼容、权限问题都会导致运行时报错
Alpine + Python 的 multi-stage 构建为何常卡在 pip install
因为 Alpine 默认用 musl 而非 glibc，很多预编译 wheel（尤其是带 C 扩展的包如 numpy、cryptography）根本不提供 musl 版本，Docker 就得现场编译——这既慢又容易缺系统依赖。
立即学习“Python免费学习笔记（深入）”；
- 加
RUN apk add --no-cache gcc musl-dev linux-headers python3-dev是必要前提，但还不够 - 更稳的做法：builder stage 用
python:3.x-slim（deb-based），final stage 用python:3.x-alpine，通过--only-binary=all强制用 wheel - 或者直接放弃 Alpine，在 final stage 用
python:3.x-slim：体积只大 ~20MB，但构建快、兼容性好、调试简单
最易被忽略的是：multi-stage 的缓存复用效果，高度依赖你是否把“变化频率”和“构建顺序”真正对齐。改一行代码就重装所有包，不是 Docker 不行，是你没把 COPY 拆够细。