一、背景与目标
说明为什么需要将 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 应用）时，两个最常见、最容易混淆的参数就是：