一、背景与目标
说明为什么需要将 FastAPI 项目打包为可执行文件。
对比传统部署方式（如 uvicorn main:app）与 PyInstaller 打包方式的区别。
适用场景：企业内网部署、Windows 服务、无 Python 环境的服务器等。
二、环境准备
Python 版本要求（推荐 Python 3.12.4+）。
FastAPI 与依赖（fastapi, uvicorn, pydantic, sqlalchemy, 等）。
安装 PyInstaller：
pip install pyinstaller
三、FastAPI 项目结构示例
展示一个典型的 FastAPI 项目结构：
复制代码
project/
├── app/
│ ├── main.py
│ ├── api/
│ ├── core/
│ ├── models/
│ ├── services/
│ └── init.py
├── requirements.txt
复制代码
并说明 main.py 中如何启动服务，例如：
import uvicorn
from app.main import app
if name == "main":
uvicorn.run(app, host="0.0.0.0", port=8000)
四、使用 PyInstaller 打包
PyInstaller是目前最流行的Python打包工具之一。它可以将Python脚本打包成独立的可执行文件，支持Windows、Linux和macOS平台。
PyInstaller 有丰富的文档，提供了详细的使用说明和常见问题解答，你可以通过以下链接访问：
PyInstaller 官方文档：https://pyinstaller.readthedocs.io
GitHub 代码库：https://github.com/pyinstaller/pyinstaller
这些文档和资源能帮助你深入了解 PyInstaller 的使用方式，并解决在打包过程中可能遇到的问题。
打包后的可执行文件可以在没有 Python 环境的机器上运行。PyInstaller 会自动分析程序的依赖关系，并将所有必要的库和资源打包到一个文件或者一个文件夹中。
打包过程中，PyInstaller 会生成一个 .spec 文件。这个文件包含了 PyInstaller 的配置信息，其中包含了构建过程的所有配置信息。你可以修改这个文件来定制打包过程。
如果我们执行下面代码
pyinstaller main.py
或者指定更多的参数的代码
pyinstaller --onefile --icon=your_icon.ico main.py
PyInstaller 都会生成一个 .spec 文件，然后可以编辑 main.spec 文件，以便进行更好的控制管理打包文件。
虽然原则上.spec文件支持跨平台的配置，不过我们在实际中往往根据不同的平台配置特定的.spec文件。
你可以手动修改 .spec 文件来添加资源文件、修改导入模块、定制输出路径等。
你可以通过编辑.spec 文件，在EXE、COLLECT和BUNDLE块下添加一个name= ，为PyInstaller提供一个更好的名字，以便为应用程序（和dist 文件夹）使用。
EXE下的名字是可执行文件的名字，BUNDLE下的名字是应用程序包的名字。
复制代码
import sys
import os
from pathlib import Path
本文件用于Window平台下打包整个项目，生成一个独立的exe文件，依赖文件松散组合
执行命令：pyinstaller main_my.spec
打包后生成文件：dist\fastapi_app\fastapi_app.exe
运行后，会在当前目录生成一个 dist 文件夹，里面有 fastapi_app.exe 文件，在命令行窗口运行该文件即可启动服务。
if sys.platform == "win32":
icon = "app/images/app.ico"
elif sys.platform == "darwin":
icon = "app/images/app.icns"
block_cipher = None
导入 PyInstaller 模块
from PyInstaller.building.build_main import Analysis
from PyInstaller.building.build_main import PYZ
from PyInstaller.building.build_main import EXE
from PyInstaller.building.build_main import COLLECT
Analysis: PyInstaller Analysis object
a = Analysis(
"app/main.py",
pathex=\[\],
binaries=\[\],
datas=[
("app/uvicorn_config.json", "app"),
("app/.env", "."),
("app/images/*", "app/images"),
("app/templates/*", "app/templates"),
("app/uploadfiles/*", "app/uploadfiles"),
("app/logs/*", "app/logs"),
],
hiddenimports=[
"uvicorn", "fastapi", "pydantic", "aiomysql", 'asyncio', # 确保依赖被正确包含
],
hookspath=\[\],
hooksconfig={},
runtime_hooks=\[\],
excludes=\[\],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
optimize=0,
)
PYZ: PyInstaller PYZ object
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
复制代码
修改完成后，执行以下命令来重新打包：
pyinstaller main_my.spec
如果我们想在Windows平台生成的dist目录中生成一个启动exe，和其他相关的Lib依赖库目录，那么我们可以适当调整下.spec文件，让它可以生成松散结构的文件目录包。
复制代码
exe = EXE(
pyz,
a.scripts,
\[\],
exclude_binaries=True,
name="fastapi_app",
debug=False,
bootloader_ignore_signals=False,
strip=False,
upx=True,
upx_exclude=\[\],
runtime_tmpdir=None,
console=True, # True = 有控制台输出（调试方便），False = 静默运行
onefile=False, # <-- False取消、True使用 onefile 模式
icon=icon, # <-- 图标路径
disable_windowed_traceback=False,
argv_emulation=False,
target_arch=None,
codesign_identity=None,
entitlements_file=None,
)
coll = COLLECT(
exe,
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
name='fastapi_app'
)
复制代码
相当于之前在exe包中的a.binaries 和 a.datas从EXE 构造函数中移到了Collect的构造函数里面了。这样会生成下面的目录结构。
image
其中_internal目录包含程序的相关依赖包和文件资源。
image
由于打包的.spec文件指定的目录结构为松散结构（使用了COLLECT构造），那么可以看到 _internal / app目录下有下面的目录结构。
image
也就是我们前面通过 Analysis 模块指定的datas集合路径的内容。
解决常见问题
缺少依赖库：如果打包后运行时出现缺少模块的错误，可以尝试将缺少的模块加入到 hiddenimports 中，或者通过 --hidden-import 选项指定：
大文件：如果使用 --onefile 时打包后的文件太大，考虑使用 --onedir 或通过压缩文件等方法进行优化。
处理资源文件：如果你的应用程序包含非 Python 代码的资源（如图像、配置文件、数据文件等），你需要通过 --add-data 选项指定资源文件的路径，或者在 .spec 文件中修改 datas 选项。
动态链接库，如果你的应用程序依赖于特定的动态链接库（如 DLL 文件或 .so 文件），你需要将这些库包含到打包中。可以在 .spec 文件的 binaries 选项中指定：
多平台支持：PyInstaller 支持 Windows、Linux 和 macOS 等多个平台，但需要在相应的平台上打包。例如，如果你要为 Windows 用户创建可执行文件，最好在 Windows 上运行 PyInstaller 来生成 Windows 的 .exe 文件。如果在 macOS 上打包，生成的文件只能在 macOS 上运行。
在使用 PyInstaller 打包 FastAPI（或其他 Python 应用）时，两个最常见、最容易混淆的参数就是：