用 Docker Compose 一键搭建 Python 学习环境：新手的第一份本地实验手册

很多刚学 Python 的朋友，第一步不是被语法难住，而是被环境难住：本机装了两个 Python 版本，pip 装包装到一半报错，跟着教程跑代码却提示找不到模块。换一台电脑，又要把这些折腾重来一遍。Docker Compose 正好能解决这个痛点：把 Python 版本、依赖和运行方式写进一个文件里，谁来用都是一条命令启动同一套环境。今天我们就用它搭一个干净、可重复的 Python 学习环境。

一、准备工作：先确认 Docker 能用

开始前，先在电脑上安装 Docker Desktop，安装完成后打开终端，输入下面两条命令验证：

docker --version
docker compose version

两条命令都能输出版本号，就说明环境就绪。如果提示找不到命令，一般是安装后没有重启终端，或者 Docker Desktop 还没有启动，重启后再试一次即可。

二、项目结构：三个文件就够了

在桌面新建一个文件夹 learn-python，里面放三个文件：

learn-python/
├── docker-compose.yml
├── app/
│   └── main.py
└── requirements.txt

这样分工很清楚：docker-compose.yml 负责“怎么跑”，app/main.py 负责“跑什么”，requirements.txt 负责“装哪些包”。以后换项目，照着这个结构复制一份就行。

三、写配置文件：把环境写成文字

在 docker-compose.yml 里写入：

services:
  python-learn:
    image: python:3.12-slim
    container_name: python-learn
    working_dir: /app
    volumes:
      - ./app:/app
    command: python main.py

这里有几个关键点值得新手记住。image 指定了 Python 3.12 的精简镜像，版本写死可以避免“昨天能跑、今天不行”的问题；volumes 把本地的 app 目录映射进容器，本地改代码，容器里立刻就能看到，不用反复复制文件；command 是容器启动后默认执行的命令。

四、写第一个 Python 程序

在 app/main.py 里写一个很小的程序，用来验证环境，也顺便练练手：

def main():
    names = ["小云", "小码", "小舟"]
    for name in names:
        print(f"你好，{name}，欢迎来到 Python 学习环境！")

if __name__ == "__main__":
    main()

再在 requirements.txt 里写一行 requests，表示我们预留了一个常用的第三方库。文件内容很少，但流程是完整的：环境、代码、依赖三者第一次配合起来。

五、启动并验证：一条命令看到结果

回到 learn-python 目录，执行：

docker compose up

第一次运行会先拉取 Python 镜像，耐心等一会儿。看到三行“你好”输出，就说明环境通了。想停下来，按 Ctrl+C，再执行 docker compose down 清理容器。之后每次练习，只要改好代码再执行 docker compose up，就能马上看到新结果。

六、新手最常踩的五个坑

第一，端口被占用。如果以后加了 Web 服务，启动时报端口已被使用，先检查本机有没有同端口的程序在跑，再换一个端口映射。第二，镜像拉取很慢。这通常是网络问题，换个时间再试，或者检查镜像加速配置，不要反复删除重装。第三，文件改了没生效。先确认 volumes 的路径写对了，相对路径是相对配置文件所在目录的。第四，容器一启动就退出。这往往是 command 指定的文件或命令写错了，用 docker compose logs 看一眼报错信息再改。第五，依赖装不上。先确认依赖清单里的包名拼写正确，再在容器里单独执行一次 pip install 定位问题。

七、可以继续加的两个小练习

环境搭好后，可以做两个延伸练习。第一个是把依赖清单里的 requests 真正用起来，写一段请求公开接口并打印返回状态码的代码，练习异常处理。第二个是给服务加一个端口映射，写一个简单的 HTTP 服务，在浏览器里访问它。这两个练习都不难，但能让你把“容器里跑代码”变成“容器里跑服务”，是很有成就感的一步。

小结

用 Docker Compose 搭 Python 学习环境，核心思路只有一句话：把环境写成文件，而不是记在脑子里。一个配置文件管运行方式，一个依赖清单管依赖，一个 app 目录管代码。环境可以删除重建，代码永远留在本地。这样学 Python，你可以把精力放在语法和思路上，而不是反复和环境较劲。把这份手册保存下来，下次换电脑、换项目，复制一份、改两行配置，就能马上开始写代码。