Docker 入门第一课：把你的 Python 小项目装进容器并跑起来

很多初学者第一次听说 Docker，都会被镜像、容器、仓库这些名词吓住。其实 Docker 的核心思想很简单：把程序和它运行所需的环境打包在一起，走到哪里都能一样跑起来。本文用一个最常见的 Python 小项目做例子，带你从零完成第一次容器化。

一、为什么需要容器

你有没有遇到过这种情况：代码在自己电脑上跑得好好的，换一台机器就报错，不是缺依赖，就是 Python 版本不对。传统做法是写一份长长的环境说明，让每个人照着装，费时还容易出错。容器解决的就是这个问题：镜像里装好了代码、依赖和运行环境，容器启动时就是一份可复现的环境。

对新手来说，先记住三个概念就够了。镜像是只读的模板，像安装包；容器是镜像跑起来的实例，像装好后的程序；仓库是存放镜像的地方，类似应用市场。

二、准备一个 Python 小项目

先写一个最简单的 Web 服务，只用标准库，不引入额外依赖，这样排错最容易。新建目录 hello-docker，写一个 app.py 文件：

from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "text/plain; charset=utf-8")
        self.end_headers()
        self.wfile.write("你好，容器里的 Python！".encode("utf-8"))

if __name__ == "__main__":
    HTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

先在本地跑一下：执行 python app.py，再用浏览器打开 localhost:8000，能看到问候语就说明程序本身没问题。这一步很重要，先保证程序能跑，再容器化，出了问题才知道是程序的问题还是容器的问题。

三、写第一份 Dockerfile

在同一目录新建一个名为 Dockerfile 的文件，内容如下：

FROM python:3.12-slim
WORKDIR /app
COPY app.py .
EXPOSE 8000
CMD ["python", "app.py"]

这五行每一行都有明确分工。FROM 选基础镜像，这里用官方的轻量 Python 镜像；WORKDIR 设定工作目录；COPY 把代码拷进镜像；EXPOSE 声明服务端口；CMD 是容器启动时执行的命令。新手常犯的错误是把 FROM 写成最新版却不固定版本，建议写明 3.12 这样的具体版本，复现性更好。

四、构建镜像并运行容器

在项目目录执行构建命令，给镜像起个名字：

docker build -t hello-docker:v1 .

构建成功后运行容器，并把主机的 8000 端口映射到容器：

docker run -d -p 8000:8000 --name hello hello-docker:v1
docker ps
docker logs hello

再次打开 localhost:8000，看到同样的问候语，第一次容器化就成功了。docker ps 能看到正在运行的容器，docker logs 能看到它的输出，这两个命令是新手排错时最常用的帮手。

五、新手最容易踩的四个坑

第一，端口映射写反。-p 后面是“主机端口:容器端口”，程序在容器里监听 8000，就要保证右边是 8000。第二，程序只监听 127.0.0.1。容器里必须监听 0.0.0.0，否则主机访问不到。第三，构建时把整个目录都拷进去，包括虚拟环境和缓存文件。加一个 .dockerignore 文件，写上 __pycache__、venv、git 目录，能让镜像小很多、构建快很多。第四，容器停了就以为数据丢了。容器本身不适合存重要数据，需要持久化时再用数据卷挂载，这是下一步要学的内容。

六、接下来学什么

跑通第一个容器后，建议按这个顺序继续：先学会 docker stop、docker rm、docker images 这些日常管理命令；再学 docker-compose，把“一个服务”扩展成“多个服务一起跑”；最后学多阶段构建和镜像瘦身，把镜像体积降下来。

容器化不是目的，让环境可复现、让部署可预期才是目的。从一个只有十几行代码的小项目开始，亲手构建并运行一次，比读十篇概念文章更管用。现在就打开终端，试试你的第一个容器吧。