背景与目标

• 说明为什么需要将 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'
)