咱们先盘盘，你面前有哪几条路？

好，咱们先来把市面上最主流的三种打法捋一遍。你可以把打包理解成“搬家”：

🔹 方式一：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-bookworm

WORKDIR /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.exe"

nssm set MyFastAPI AppParameters "main:app --host 0.0.0.0 --port 8080"

nssm 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 香得多。

🔹 场景C：Windows 服务器，不能装 Python，不能开虚拟机。

🔸 上 PyInstaller。
记住我踩的坑，去改 Spec 文件，用 --onedir 模式。

🔹 场景D：Windows 服务器，能装 Python，想当服务跑。

🔸 NSSM + 虚拟环境。
这是 Windows 下最接近“优雅”二字的方案了。

---

其实工具的选择就是这么个理儿：没有银弹，只有场景适配。