基于Python的FastAPI后端开发框架如何使用PyInstaller 进行打包与部署

我在随笔《WxPython跨平台开发框架之使用PyInstaller 进行打包处理》中介绍过如何使用PyInstaller 进行打包处理的一些过程和事项。我们基于Python的FastAPI后端应用，在实际开发的时候，直接运行main.py 进行调试即可，但是部署的时候，我们就需要把它们进行打包处理，这里首选PyInstaller 进行打包。本文详细介绍了 如何使用 PyInstaller 对基于 Python 的 FastAPI 后端项目进行打包与部署，使其能够在目标环境中以独立可执行文件的形式运行，无需安装 Python 解释器或额外依赖。文章面向希望将 FastAPI 服务打包为独立运行服务的开发者，特别适用于企业内部系统或需要简化部署的场景。
一、背景与目标

• 说明为什么需要将 FastAPI 项目打包为可执行文件。
  
• 对比传统部署方式（如 uvicorn main:app）与 PyInstaller 打包方式的区别。
  
• 适用场景：企业内网部署、Windows 服务、无 Python 环境的服务器等。
  

二、环境准备

• Python 版本要求（推荐 Python 3.12.4+）。
  
• FastAPI 与依赖（fastapi, uvicorn, pydantic, sqlalchemy, 等）。
  
• 安装 PyInstaller：
  

1. pip install pyinstaller

复制代码

三、FastAPI 项目结构示例

展示一个典型的 FastAPI 项目结构：

1. project/
2. ├── app/
3. │   ├── main.py
4. │   ├── api/
5. │   ├── core/
6. │   ├── models/
7. │   ├── services/
8. │   └── __init__.py
9. ├── requirements.txt<br>

复制代码

并说明 main.py 中如何启动服务，例如：

1. import uvicorn
2. from app.main import app
4. if __name__ == "__main__":
5.     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 的配置信息，其中包含了构建过程的所有配置信息。你可以修改这个文件来定制打包过程。
如果我们执行下面代码

1. pyinstaller main.py

复制代码

或者指定更多的参数的代码

1. pyinstaller --onefile --icon=your_icon.ico main.py

复制代码

PyInstaller 都会生成一个 .spec 文件，然后可以编辑 main.spec 文件，以便进行更好的控制管理打包文件。
虽然原则上.spec文件支持跨平台的配置，不过我们在实际中往往根据不同的平台配置特定的.spec文件。
你可以手动修改 .spec 文件来添加资源文件、修改导入模块、定制输出路径等。
你可以通过编辑.spec 文件，在EXE、COLLECT和BUNDLE块下添加一个name= ，为PyInstaller提供一个更好的名字，以便为应用程序（和dist 文件夹）使用。
EXE下的名字是可执行文件的名字，BUNDLE下的名字是应用程序包的名字。

1. import sys
2. import os
3. from pathlib import Path
5. # 本文件用于Window平台下打包整个项目，生成一个独立的exe文件，依赖文件松散组合
6. # 执行命令：pyinstaller main_my.spec
7. # 打包后生成文件：dist\fastapi_app\fastapi_app.exe
8. # 运行后，会在当前目录生成一个 dist 文件夹，里面有 fastapi_app.exe 文件，在命令行窗口运行该文件即可启动服务。
11. if sys.platform == "win32":
12.     icon = "app/images/app.ico"
13. elif sys.platform == "darwin":
14.     icon = "app/images/app.icns"
16. block_cipher = None
18. # 导入 PyInstaller 模块
19. from PyInstaller.building.build_main import Analysis
20. from PyInstaller.building.build_main import PYZ
21. from PyInstaller.building.build_main import EXE
22. from PyInstaller.building.build_main import COLLECT
24. # Analysis: PyInstaller Analysis object
25. a = Analysis(
26.     ["app/main.py"],
27.     pathex=[],
28.     binaries=[],
29.     <strong>datas</strong>=[
30.         ("app/uvicorn_config.json", "app"),
31.         ("app/.env", "."),
32.         ("app/images/*", "app/images"),
33.         ("app/templates/*", "app/templates"),
34.         ("app/uploadfiles/*", "app/uploadfiles"),
35.         ("app/logs/*", "app/logs"),
36.     ],
37.     <strong>hiddenimports</strong>=[
38.          "uvicorn", "fastapi", "pydantic", "aiomysql", 'asyncio',   # 确保依赖被正确包含
39.     ],
40.     hookspath=[],
41.     hooksconfig={},
42.     runtime_hooks=[],
43.     excludes=[],
44.     win_no_prefer_redirects=False,
45.     win_private_assemblies=False,
46.     cipher=block_cipher,
47.     noarchive=False,
48.     optimize=0,
49. )
51. # PYZ: PyInstaller PYZ object
52. pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

复制代码

修改完成后，执行以下命令来重新打包：

1. pyinstaller main_my.spec

复制代码

如果我们想在Windows平台生成的dist目录中生成一个启动exe，和其他相关的Lib依赖库目录，那么我们可以适当调整下.spec文件，让它可以生成松散结构的文件目录包。
[code]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,  #