Flask/FastAPI部署至Google Cloud遇503错误，本地运行正常

一、端口配置必须匹配平台要求 #

不管是App Engine还是Cloud Run，平台都会把请求转发到**8080端口**（或通过PORT环境变量指定的端口），你的代码必须监听这个端口，不能硬编码本地常用的5000/8000：

• Flask示例：app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))
• FastAPI示例：uvicorn.run(app, host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))
  必须读取PORT环境变量，因为平台会动态分配端口，硬编码会导致服务无法接收请求。

二、依赖清单要完整且准确 #

requirements.txt必须包含生产环境所有必需的包，不能漏：

• 比如Flask项目要加Flask==2.3.3（指定版本更稳定），如果用gunicorn作为生产服务器，还要加gunicorn==21.2.0；FastAPI则要加fastapi==0.104.1和uvicorn==0.24.0.post1。
• 本地开发时虚拟环境里有的包，部署时如果没写进requirements，会直接导致服务启动失败。

三、启动命令要用生产级服务器 #

别用本地开发的启动命令部署：

• App Engine的app.yml里，entrypoint要写生产服务器命令，比如gunicorn -b :$PORT app:app（app:app指的是app.py文件里的Flask实例app），不能写flask run。
• Cloud Run部署时，启动命令要写uvicorn main:app --host 0.0.0.0 --port $PORT，别加--reload（这是本地热重载用的）。

四、优先看日志找具体错误 #

503大多是服务启动失败导致的，直接去Cloud Console看日志：

• GAE：进入App Engine→日志，筛选stderr或crash条目，找模块导入失败、端口绑定错误、文件不存在这类具体报错。
• Cloud Run：进入对应服务→日志，查看启动阶段的错误信息，比如依赖安装失败、代码语法错误。
  日志里会明确告诉你问题出在哪，别瞎试偏方（比如加favicon路由，这根本解决不了核心问题）。

五、检查服务访问权限与网络设置 #

• 测试阶段先把服务权限设为允许所有用户访问，排除权限导致的访问拦截。
• 如果是Cloud Run，别设置私有网络限制，确保公网能正常访问；App Engine标准环境默认是公网可访问，除非你配置了VPC限制。

六、代码入口与路径要正确 #

• 确认代码入口文件的实例名对应正确：比如Flask里是app = Flask(__name__)，启动命令里就要用app:app；FastAPI里是app = FastAPI()，如果文件名是main.py，就用main:app。
• 别用本地绝对路径读取文件，部署后路径和本地不一样，要用相对路径或环境变量指定的路径。

内容的提问来源于stack exchange，提问作者Shake Systems