VSCode Remote-Containers 不自动持久化容器修改，必须二选一使用 image（开箱即用但重启丢失改动）或 build（定制 Dockerfile 实现真持久化），且二者不可共存；build 模式下需显式安装 vscode-server、合理配置 forwardPorts 和 postCreateCommand，并注意 Docker 缓存失效陷阱。
VSCode 的 Remote-Containers 不会自动持久化你改过的容器镜像——每次 Reopen in Container 都可能拉新镜像或重建容器，除非你明确告诉它“用我本地已有的、带修改的镜像”。所谓“持久化”，本质是控制镜像来源和构建缓存复用，不是保存运行中容器的状态。
devcontainer.json 里 image 和 build 字段不能共存
这是最常踩的坑：同时写 "image" 和 "build"，VSCode 直接报错退出，连容器都不起。二者必须二选一：
-
"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11-bullseye"—— 适合开箱即用，镜像拉下来就跑，但所有改动（比如 pip install 新包）重启后丢失 -
"build": { "dockerfile": "Dockerfile" }—— 所有定制必须写进Dockerfile，构建出的镜像带你的改动，下次重开直接复用本地镜像层，这才是真持久化
新手别贪快用 image，想留环境就得切到 build 模式。
build 模式下 Dockerfile 必须显式安装 vscode-server
VSCode 要在容器里启动编辑器服务，依赖 vscode-server。官方预置镜像（如 mcr.microsoft.com/vscode/devcontainers/python:3.11）自带它；但你自己写的 Dockerfile 如果只是 FROM python:3.11-slim，那容器起来后只有黑屏终端，VSCode 根本连不上。
正确做法是：
- 要么基于官方基础镜像：
FROM mcr.microsoft.com/devcontainers/base:ubuntu - 要么手动装：
RUN curl -fsSL https://aka.ms/vscode-server-release | tar -xzf - -C /usr/local/share/code-server --strip-components=1（路径和版本需匹配 VSCode 当前 Remote-Containers 扩展要求）
漏掉这步，Reopen in Container 后卡在 “Installing VS Code Server…” 就是它。
forwardPorts + postCreateCommand 是调试和环境初始化的关键组合
端口不转发，宿主机浏览器打不开 localhost:5000；环境没初始化，每次重开都要手动 pip install -r requirements.txt——这两件事必须写进 devcontainer.json，否则不算真正持久化。
示例配置片段：
{
"name": "Python Dev",
"build": { "dockerfile": "Dockerfile" },
"forwardPorts": [5000, 8000],
"postCreateCommand": "pip install -r requirements.txt && python -m spacy download en_core_web_sm",
"customizations": {
"vscode": {
"extensions": ["ms-python.python"]
}
}
}
postCreateCommand 只在容器首次创建时执行一次，结果固化在镜像层里；后续重开直接复用，不用再等安装。
镜像层缓存失效的三个隐形原因
你以为写了 build 就能复用缓存？不一定。以下情况会让 Docker 完全跳过缓存，重新拉基础镜像、重跑所有指令：
-
Dockerfile里用了RUN apt update && apt install -y xxx——apt update时间戳总变，导致后续层全失效；应合并为RUN apt update && apt install -y xxx && apt clean -
COPY . /workspace放得太早，只要项目根目录下任意文件改了，后续所有 RUN 指令都缓存失效；应把COPY尽量往后放，只复制必要文件（比如先COPY requirements.txt，装完依赖再COPY .） -
devcontainer.json里改了build.context或build.dockerfile路径，Docker 就当全新构建，旧缓存作废
缓存不是开关，是分层哈希比对；改一行，后面全重来。
