python: 使用Pyinstaller把FastAPI项目打包成exe文件

### 使用 PyInstaller 打包 FastAPI 应用程序 FastAPI 是一个现代、快速（高性能）的 Web 框架，用于构建 API 服务。然而，由于其异步特性和依赖项较多，在使用 PyInstaller 进行打包时可能会遇到一些挑战。 #### 准备工作 为了确保 FastAPI 应用可以被成功打包并正常运行，建议先安装必要的库： ```bash pip install fastapi uvicorn pyinstaller ``` #### 修改 `main.py` 文件 通常情况下，FastAPI 的入口文件是 `main.py` 或类似的 Python 脚本。为了让 PyInstaller 正确识别所有的模块和路径，可以在脚本顶部添加如下代码来设置环境变量[^1]： ```python import os if getattr(sys, 'frozen', False): os.chdir(sys._MEIPASS) from fastapi import FastAPI app = FastAPI() @app.get("/") async def read_root(): return {"message": "Hello World"} ``` 这段代码的作用是在冻结状态下改变当前的工作目录到解压后的临时位置，从而使得相对路径下的静态资源能够被正确访问。 #### 创建 spec 文件 (可选) 对于复杂的项目结构或者有特殊需求的情况下，创建 `.spec` 文件是非常有用的。通过命令 `pyi-makespec --onefile main.py` 可以生成默认配置的 `.spec` 文件，并在此基础上做进一步调整优化。 #### 添加隐式导入 某些时候，PyInstaller 并不能自动检测出所有需要被打包进去的模块。这时可以通过修改 `.spec` 文件中的 `hiddenimports` 列表或直接在命令行参数里指定额外要包含的内容[^2]： ```bash pyinstaller --add-binary="path/to/your/static/files;static" \ --hidden-import=uvicorn.main \ --hidden-import=fastapi.routing \ main.py ``` 这里假设存在名为 `static` 的文件夹作为静态资源存储的位置；同时指定了几个常见的隐藏导入项以确保这些组件不会缺失而导致错误发生。 #### 启动方式的选择 考虑到 FastAPI 默认使用的 ASGI 协议以及 Uvicorn 服务器的特点，在最终的应用启动部分应当采用适当的方式调用 Uvicorn 来托管 FastAPI 实例。一种常见做法是在主函数中加入以下逻辑： ```python if __name__ == "__main__": import uvicorn if not hasattr(sys, '_MEIPASS'): # 开发模式下直接启动Uvicorn uvicorn.run(app='main:app', host="0.0.0.0", port=8000, reload=True) else: # 生产环境中禁用热重载功能 uvicorn.run(app='main:app', host="0.0.0.0", port=8000) ``` 这样既能在开发阶段享受实时更新带来的便利，又能够在发布版中保持稳定高效的性能表现。 #### 完成打包操作 完成上述准备工作之后，就可以正式执行打包指令了。如果之前已经创建好了自定义的 `.spec` 文件，则可以直接基于该文件来进行打包处理；反之则继续沿用简单的单文件形式： ```bash pyinstaller -F -n my_fastapi_app main.py ``` 这将会把整个 FastAPI 应用及其所需的所有依赖都压缩进一个独立的可执行文件当中去。