基于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：
pip install pyinstaller三、FastAPI 项目结构示例
展示一个典型的 FastAPI 项目结构：
project/
├── app/
│ ├── main.py
│ ├── api/
│ ├── core/
│ ├── models/
│ ├── services/
│ └── __init__.py
├── requirements.txt<br>并说明 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.pyPyInstaller 都会生成一个 .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=[],
<strong>datas</strong>=[
("app/uvicorn_config.json", "app"),
("app/.env", "."),
("app/images/*", "app/images"),
("app/templates/*", "app/templates"),
("app/uploadfiles/*", "app/uploadfiles"),
("app/logs/*", "app/logs"),
],
<strong>hiddenimports</strong>=[
"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,#
页:
[1]