用 Docker 搭 Python 开发环境,核心目标只有三个:依赖一致、环境可重建、和宿主机隔离。本章从零开始,覆盖镜像选型、Dockerfile、Compose、依赖管理、远程调试、数据库依赖和常见坑,最后给一份可直接套用的完整配置。参考:Docker Python 指南。
一、为什么用 Docker 做 Python 开发
- 依赖一致:Python 版本、系统库、pip 包全部锁在镜像里,不会出现「我这能跑」;
- 环境可重建:删掉容器重来一遍即可,不污染宿主机;
- 多版本并存:3.9、3.11、3.12 各跑一个容器,互不干扰;
- 依赖服务一键起:PostgreSQL、Redis、RabbitMQ 用 Compose 一起拉起;
- 贴近生产:开发用的镜像和线上镜像可以共用同一份 Dockerfile。
二、三种方案怎么选
| 方案 | 做法 | 适合 |
|---|---|---|
| 官方镜像 + 挂载代码 | docker run -v $PWD:/app python:3.12 | 临时脚本、快速验证 |
| 自建 Dockerfile | 写依赖、系统包、用户,docker build | 正式项目、团队协作 |
| Dev Containers | VS Code 连接容器开发 | 需要 IDE 补全、调试、终端一体化 |
实际项目推荐「自建 Dockerfile + Compose 编排 + Dev Containers 接入」组合。
三、项目结构
myproject/
├─ app/
│ ├─ __init__.py
│ ├─ main.py
│ └─ settings.py
├─ tests/
│ └─ test_main.py
├─ requirements.txt
├─ Dockerfile
├─ docker-compose.yml
├─ .dockerignore
└─ .devcontainer/
└─ devcontainer.json
四、编写开发用 Dockerfile
FROM python:3.12-slim
# 基础环境变量
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
TZ=Asia/Shanghai
WORKDIR /app
# 换国内 apt 源并安装系统依赖(编译型包需要 build-essential)
RUN sed -i 's@deb.debian.org@mirrors.aliyun.com@g' /etc/apt/sources.list.d/debian.sources \
&& apt-get update \
&& apt-get install -y --no-install-recommends \
build-essential libpq-dev curl git tzdata \
&& rm -rf /var/lib/apt/lists/*
# 先拷依赖清单,利用层缓存
COPY requirements.txt .
RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
# 再拷源码
COPY . .
# 非 root 用户运行
RUN useradd -m -u 1000 dev && chown -R dev:dev /app
USER dev
CMD ["python", "-m", "app"]
几个关键点:
PYTHONUNBUFFERED=1让日志实时输出,不会卡在缓冲区;PYTHONDONTWRITEBYTECODE=1避免容器里到处是__pycache__;- 先
COPY requirements.txt再安装依赖,改代码不会触发重装; - 用非 root 用户运行,挂载目录权限也更可控。
五、docker-compose 开发编排
services:
app:
build: .
command: python -m app
volumes:
- .:/app
ports:
- "8000:8000"
- "5678:5678" # debugpy
environment:
- DATABASE_URL=postgresql://app:app@db:5432/app
- REDIS_URL=redis://redis:6379/0
- PYTHONPATH=/app
depends_on:
- db
- redis
tty: true
db:
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: app
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
ports:
- "5432:5432"
redis:
image: redis:7
ports:
- "6379:6379"
volumes:
pgdata:
docker compose up -d --build
docker compose exec app bash
docker compose logs -f app
docker compose down
volumes: .:/app 让宿主机改代码立即生效;depends_on 只保证启动顺序,不保证服务就绪,应用里最好加重试。
六、依赖管理
1. requirements.txt
fastapi==0.115.0
uvicorn[standard]==0.30.6
psycopg[binary]==3.2.3
redis==5.2.0
pytest==8.3.4
debugpy==1.8.8
2. pyproject.toml + uv
COPY pyproject.toml uv.lock ./
RUN pip install uv \
&& uv sync --frozen
3. 分层缓存技巧
依赖文件不变就不重装;可以用「先装基础依赖,再装开发依赖」拆成两个文件:
requirements.txt # 运行时依赖
requirements-dev.txt # 测试、调试、格式化工具
七、常用开发工具
1. 交互式 Shell
docker compose exec app python
docker compose exec app ipython
2. 测试与格式化
docker compose exec app pytest -q
docker compose exec app ruff check .
docker compose exec app black .
3. 远程调试(debugpy)
RUN pip install debugpy
docker compose exec app \
python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m app
VS Code 的 launch.json 配置:
{
"name": "Attach to Docker",
"type": "debugpy",
"request": "attach",
"connect": { "host": "127.0.0.1", "port": 5678 },
"pathMappings": [
{ "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }
]
}
八、Dev Containers(VS Code)
{
"name": "python-dev",
"dockerComposeFile": "../docker-compose.yml",
"service": "app",
"workspaceFolder": "/app",
"customizations": {
"vscode": {
"extensions": [
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"
]
}
}
}
用 VS Code 的「Reopen in Container」打开项目,终端、调试、补全全部在容器里,宿主机不需要装 Python。
PyCharm 则可以在「Interpreter → Docker Compose」里指定 service,自动识别容器内的解释器。
九、数据库与缓存的初始化
# initdb/001-init.sql
CREATE TABLE IF NOT EXISTS users (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL
);
db:
image: postgres:16
volumes:
- pgdata:/var/lib/postgresql/data
- ./initdb:/docker-entrypoint-initdb.d:ro
放在 /docker-entrypoint-initdb.d 下的 .sql、.sh 会在数据库首次初始化时执行。
十、Jupyter Notebook 场景
docker run -d --name jupyter \
-p 8888:8888 \
-v $PWD:/home/jovyan/work \
jupyter/scipy-notebook:latest
docker logs jupyter | grep token
需要固定密码时,用 jupyter server password 生成配置后挂载到容器。
十一、生产与开发的差异
| 维度 | 开发 | 生产 |
|---|---|---|
| 启动命令 | python -m app / debugpy | gunicorn / uvicorn --workers |
| 代码 | 挂载宿主机目录 | 打进镜像 |
| 调试工具 | 包含 pytest、debugpy | 不安装 |
| 用户 | root 或 dev 均可 | 非 root |
| 镜像 | 体积不敏感 | 多阶段构建、slim/alpine |
# 生产阶段示例
FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .
USER 1000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
十二、常见问题
- pip 安装慢:在 Dockerfile 里指定清华/阿里源,或配置全局
pip.conf; - 时区不对:设置
TZ=Asia/Shanghai并安装tzdata; - 挂载目录权限:容器内 UID 与宿主机不一致,用
useradd -u 1000对齐,或构建时传--build-arg UID=$(id -u); - 改代码不生效:确认
volumes挂的是源码目录,且应用支持热重载; - 文件监听失效:挂载卷上的 inotify 可能不工作,改用 polling 模式(如 uvicorn
--reload配合 watchdog); - Apple Silicon 拉 amd64 镜像:加
--platform linux/amd64,或改用 arm64 版本; - 容器访问宿主机服务:Linux 用宿主 IP 或
host-gateway,Docker Desktop 用host.docker.internal; - 端口被占用:改宿主机端口,如
8001:8000; - 镜像越来越大:清理 apt 缓存、用
--no-install-recommends、多阶段构建、.dockerignore排除无关文件。
十三、完整可运行的最小配置
# .dockerignore
.git
__pycache__
*.pyc
.venv
.env
node_modules
docker compose up -d --build
docker compose exec app python -c "import sys; print(sys.version)"
curl -I http://127.0.0.1:8000
到这里,一个「代码热更新 + 依赖固定 + 数据库/Redis 就绪 + 可远程调试」的 Python 开发环境就跑起来了。
十四、总结
用 python:3.12-slim 做基础镜像,先装系统依赖、再装 pip 依赖、最后拷源码;Compose 挂载代码并编排数据库与缓存;用 debugpy 或 Dev Containers 接入 IDE;开发与生产分离,生产用多阶段构建和非 root 运行。