咱们先来把市面上最主流的三种打法捋一遍。你可以把打包理解成“搬家” 方式一PyInstaller (粗暴打包流)比喻把整个家当塞进一个集装箱里拖到地方直接开箱。优点一个文件夹走天下不需要目标机器装Python。痛点极其容易漏掉隐式依赖踩坑率极高。 方式二虚拟环境 源码拷贝 (原生依赖流)比喻只搬家具过去到了新家再按照清单requirements.txt现买锅碗瓢盆。优点最稳体积小兼容性最好。痛点目标机器必须有Python环境。 方式三Docker 容器化 (拎包入住流)比喻直接把整个旧房间的布局和家具克隆过去连墙纸都一样。优点环境完全隔离Linux下部署的首选方案。痛点Windows下依赖虚拟化有点重且图形化交互麻烦。 Linux 环境下听我一句劝别折腾直接容器化在Linux下真的信我无脑选 Docker。你别看PyInstaller能打包成单个文件很诱人但在Linux生态里那真是自找麻烦。 Docker 实操把大象装进冰箱分三步第一步编写 Dockerfile别一上来就找网上的烂大街模板。这里有一点要特别注意requirements.txt里千万别忘了写死uvicorn[standard]否则进容器跑起来你会发现性能怎么这么拉胯就是因为缺了那几个 C 扩展。# 用slim镜像体积小安全漏洞少FROM python:3.14-slim-bookwormWORKDIR /app# 先复制依赖文件利用Docker缓存层不用每次都重装COPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt# 再把代码丢进去COPY . .# 重点用字符串形式启动不然信号传递会有问题CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 80]第二步构建并运行你说“这命令我都会有啥好讲的”嘿还真有。挂载卷的时候尽量用绝对路径。特别是配合一些CI/CD工具时相对路径经常导致挂载了个寂寞。docker build -t my-fastapi-app .docker run -d -p 8080:80 --name my-app my-fastapi-app第三步善用 docker-compose如果涉及数据库或者Redis别用那个长长的docker run指令了维护性太差。写个docker-compose.yml谁看了不夸一句清爽 Windows 环境下在现实的泥潭里优雅地扑腾Windows 服务器往往是企业内网的“硬骨头”。不能装 Docker Desktop因为要开Hyper-V很多虚机不支持甚至不给装 Python。这时候PyInstaller 硬着头皮也得上但我带你避开那些巨坑。 PyInstaller 避坑指南官方文档虽然没写那么细但根据以往的经验你绝对不能直接pyinstaller main.py这么做生成的包要么启动闪退要么找不到uvicorn的二进制依赖。正确姿势使用 Spec 文件进行精细化控制。第一步生成 Spec 文件pyinstaller --name myapp --onedir main.py# 注意是 --onedir 不是 --onefile为什么不用--onefile因为单文件运行时每次都要解压到临时目录对于 FastAPI 这种需要频繁 IO 的子进程应用启动慢不说杀毒软件还经常误以为你是病毒给拦下来血泪教训。第二步修改myapp.spec文件这个步骤最考验耐心。咱们要手动把隐式依赖揪出来。# -*- mode: python ; coding: utf-8 -*-a Analysis([main.py],pathex[],binaries[],# 重点来了这里要补上 uvicorn 的隐式依赖hiddenimports[uvicorn.logging,uvicorn.loops.auto,uvicorn.protocols.http.auto,fastapi.encoders,],...)pyz PYZ(a.pure)exe EXE(pyz, ...)第三步重新打包pyinstaller myapp.spec打包完后去dist/myapp目录下找你的myapp.exe把它和整个文件夹一起拷走。 原生环境 NSSM如果你能装 Python那我就更推荐你用原生环境 NSSM (Non-Sucking Service Manager)把 FastAPI 注册成 Windows 服务。是不是以为刚才 Docker 那种跑法就够稳了在 Windows 生产环境里你如果只是双击 exe 或者开个 CMD 窗口万一谁手贱把窗口关了服务就挂了。这时候就该 NSSM 出场了nssm install MyFastAPI C:\Python311\Scripts\uvicorn.exenssm set MyFastAPI AppParameters main:app --host 0.0.0.0 --port 8080nssm start MyFastAPI这样它就在后台像个小强一样顽强地活着崩溃了还能自动重启。 最后的抉择我该怎么选说到这里咱们来划个重点。选择恐惧症的同学看这里 场景A我有 Linux 服务器能联网。冲 Docker。别想了这是工程上的最佳实践。 场景B我有 Linux 服务器但完全离线涉密内网。用 Docker save/load。先在有网机器上docker save -o app.tar my-app:latest然后U盘拷过去docker load -i app.tar这也比 PyInstaller 香得多。 场景CWindows 服务器不能装 Python不能开虚拟机。
咱们先盘盘，你面前有哪几条路？
咱们先来把市面上最主流的三种打法捋一遍。你可以把打包理解成“搬家” 方式一PyInstaller (粗暴打包流)比喻把整个家当塞进一个集装箱里拖到地方直接开箱。优点一个文件夹走天下不需要目标机器装Python。痛点极其容易漏掉隐式依赖踩坑率极高。 方式二虚拟环境 源码拷贝 (原生依赖流)比喻只搬家具过去到了新家再按照清单requirements.txt现买锅碗瓢盆。优点最稳体积小兼容性最好。痛点目标机器必须有Python环境。 方式三Docker 容器化 (拎包入住流)比喻直接把整个旧房间的布局和家具克隆过去连墙纸都一样。优点环境完全隔离Linux下部署的首选方案。痛点Windows下依赖虚拟化有点重且图形化交互麻烦。 Linux 环境下听我一句劝别折腾直接容器化在Linux下真的信我无脑选 Docker。你别看PyInstaller能打包成单个文件很诱人但在Linux生态里那真是自找麻烦。 Docker 实操把大象装进冰箱分三步第一步编写 Dockerfile别一上来就找网上的烂大街模板。这里有一点要特别注意requirements.txt里千万别忘了写死uvicorn[standard]否则进容器跑起来你会发现性能怎么这么拉胯就是因为缺了那几个 C 扩展。# 用slim镜像体积小安全漏洞少FROM python:3.14-slim-bookwormWORKDIR /app# 先复制依赖文件利用Docker缓存层不用每次都重装COPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt# 再把代码丢进去COPY . .# 重点用字符串形式启动不然信号传递会有问题CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 80]第二步构建并运行你说“这命令我都会有啥好讲的”嘿还真有。挂载卷的时候尽量用绝对路径。特别是配合一些CI/CD工具时相对路径经常导致挂载了个寂寞。docker build -t my-fastapi-app .docker run -d -p 8080:80 --name my-app my-fastapi-app第三步善用 docker-compose如果涉及数据库或者Redis别用那个长长的docker run指令了维护性太差。写个docker-compose.yml谁看了不夸一句清爽 Windows 环境下在现实的泥潭里优雅地扑腾Windows 服务器往往是企业内网的“硬骨头”。不能装 Docker Desktop因为要开Hyper-V很多虚机不支持甚至不给装 Python。这时候PyInstaller 硬着头皮也得上但我带你避开那些巨坑。 PyInstaller 避坑指南官方文档虽然没写那么细但根据以往的经验你绝对不能直接pyinstaller main.py这么做生成的包要么启动闪退要么找不到uvicorn的二进制依赖。正确姿势使用 Spec 文件进行精细化控制。第一步生成 Spec 文件pyinstaller --name myapp --onedir main.py# 注意是 --onedir 不是 --onefile为什么不用--onefile因为单文件运行时每次都要解压到临时目录对于 FastAPI 这种需要频繁 IO 的子进程应用启动慢不说杀毒软件还经常误以为你是病毒给拦下来血泪教训。第二步修改myapp.spec文件这个步骤最考验耐心。咱们要手动把隐式依赖揪出来。# -*- mode: python ; coding: utf-8 -*-a Analysis([main.py],pathex[],binaries[],# 重点来了这里要补上 uvicorn 的隐式依赖hiddenimports[uvicorn.logging,uvicorn.loops.auto,uvicorn.protocols.http.auto,fastapi.encoders,],...)pyz PYZ(a.pure)exe EXE(pyz, ...)第三步重新打包pyinstaller myapp.spec打包完后去dist/myapp目录下找你的myapp.exe把它和整个文件夹一起拷走。 原生环境 NSSM如果你能装 Python那我就更推荐你用原生环境 NSSM (Non-Sucking Service Manager)把 FastAPI 注册成 Windows 服务。是不是以为刚才 Docker 那种跑法就够稳了在 Windows 生产环境里你如果只是双击 exe 或者开个 CMD 窗口万一谁手贱把窗口关了服务就挂了。这时候就该 NSSM 出场了nssm install MyFastAPI C:\Python311\Scripts\uvicorn.exenssm set MyFastAPI AppParameters main:app --host 0.0.0.0 --port 8080nssm start MyFastAPI这样它就在后台像个小强一样顽强地活着崩溃了还能自动重启。 最后的抉择我该怎么选说到这里咱们来划个重点。选择恐惧症的同学看这里 场景A我有 Linux 服务器能联网。冲 Docker。别想了这是工程上的最佳实践。 场景B我有 Linux 服务器但完全离线涉密内网。用 Docker save/load。先在有网机器上docker save -o app.tar my-app:latest然后U盘拷过去docker load -i app.tar这也比 PyInstaller 香得多。 场景CWindows 服务器不能装 Python不能开虚拟机。
