← 返回博客

Mac 用 Devio 运行 FastAPI:Python 虚拟环境、启动命令与本地域名


在 Apple Silicon Mac 上用 Devio 运行 FastAPI,需要准备 Python 解释器、项目依赖和启动参数。项目进程与 Nginx 分开管理:先让项目自己的本机端口正常响应,再配置本地域名访问,定位问题会更清楚。本文按 Devio 发布文档中的操作路径整理,不依赖全局安装 Python 包。

开始前准备什么

Devio 是免费、无需注册的 Apple Silicon Mac 本地开发环境管理器,目前未开源。请从官方下载页安装,功能以当前应用和版本说明为准。

准备一个可信的 FastAPI 项目。下面的启动示例假设项目根目录有 main.py,文件里定义了名为 app 的 FastAPI 应用;如果你的文件路径或对象名称不同,必须替换 main:app。安装依赖可能执行软件包提供的代码,请先确认项目来源。

1. 选择 Python 解释器

打开“软件管理 → 开发工具 → Python”,安装所需版本,或选择已经检测到的本机 Python。随后在“网站”创建 Python 项目,选择项目目录、解释器、目标端口和启动命令。

项目中的 .python-version 用于匹配已安装版本。手动选择和已经保存的项目版本会保留,不会因为终端里的 python3 变化就自动切换。项目需要的版本没有安装时,先补齐对应版本,不要只修改版本文件。

2. 为项目创建虚拟环境并安装依赖

在项目“管理”中创建独立的 .venv,再安装依赖。Devio 支持 requirements.txt 和标准 pyproject.toml。Poetry、uv、PDM 或 Pipenv 管理的项目,应通过对应工具管理,或先导出 requirements.txt。

确认依赖包含 FastAPI 以及本例启动命令使用的 Uvicorn。安装输出可以在“项目日志”中查看;看到安装错误时先解决依赖问题,不要反复点击启动。

3. 填写启动参数

启动命令填写交给已选择 Python 的参数:-m uvicorn main:app --host {host} --port {port}。不需要再把 python3 写到这段参数前面。

Devio 会把 {host} 替换成 127.0.0.1,把 {port} 替换成你设置的目标端口。项目以前台模式运行,关闭自动重载,不添加 --reload。若项目入口是 app/main.py 中的 app,可按实际模块布局使用 app.main:app。

4. 先验证端口,再使用本地域名

启动项目后,查看项目日志中的启动结果。若目标端口是 8000,可在浏览器访问 http://127.0.0.1:8000/docs;这适用于没有关闭或自定义 FastAPI 文档地址的项目。文档地址被修改时,使用项目实际定义的接口验证。

通过 Devio 站点域名访问前,还需要到首页手动启动 Nginx。启用域名同步会修改系统 hosts 文件的 Devio 受管理区块。直接端口可访问、域名不可访问时,重点检查 Nginx、域名配置和解析,而不是重装 Python。

常见问题怎么处理

提示 No module named uvicorn:检查依赖是否安装到了这个项目绑定的解释器或虚拟环境,而不是另一个终端环境。

提示找不到 main 或 app:检查项目目录、Python 模块路径以及应用对象名称,按实际项目修改 main:app。

端口已被占用:在“设置 → 系统设置”检测端口,确认占用来源后换用空闲目标端口,避免随意结束其他项目。

升级 Python 后无法启动:停止项目后,按需要选择“重建环境”并重新安装依赖。重建会重新建立虚拟环境,成功后原环境中的依赖会被移除,项目源码保留。

何时需要 Nginx,何时不需要

验证 FastAPI 的本机监听端口和接口时,先关注项目进程本身;需要通过 Devio 的站点域名访问时,再启动 Nginx。Devio 管理的是本地开发环境,这套步骤不等于公网生产部署。

更多常见问题见首页常见问题;其他教程见博客。


发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注