开始前你需要准备

在排查「Cloud Run 无法部署成功」前，先把地基打好。准备一个你能登录的 GCP 项目，并确认已启用结算、Cloud Run API、Artifact Registry API 和 Cloud Build API；没绑付款方式，API 可能开不了，构建或推送镜像也会半路失败。先按系统安装 Google Cloud CLI（也就是 gcloud），项目 ID 不是项目名称，在控制台首页能看到，复制时别带空格。装好后，在终端或 Cloud Shell 里复制整段命令：它会登录、让你输入项目 ID、启用三个 API，并打印结算状态。若结算不是 True，请到控制台「结算」页面绑定后再来。

gcloud version
gcloud auth login
printf "输入 GCP 项目 ID："; read -r PROJECT_ID
gcloud config set project "$PROJECT_ID"
gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com --project "$PROJECT_ID"
BILLING_ENABLED="$(gcloud beta billing projects describe "$PROJECT_ID" --format='value(billingEnabled)')"
echo "结算状态：$BILLING_ENABLED"
printf "输入区域，直接回车用 asia-east1："; read -r REGION
REGION="${REGION:-asia-east1}"
printf "输入服务名称，直接回车用 my-service："; read -r SERVICE_NAME
SERVICE_NAME="${SERVICE_NAME:-my-service}"
gcloud config set run/region "$REGION"
echo "请核对：项目=$(gcloud config get-value project) 区域=$(gcloud config get-value run/region) 服务=$SERVICE_NAME"

接着看最后一行「请核对」输出，项目、区域、服务名称必须和你的目标一致。gcloud 会记住上一次配置，这是小白最常见的坑：代码没错，却发到旧项目或其他地区，于是控制台里怎么找都找不到服务。区域也别随手改，最好选离用户近、且数据库等资源也放一起的地方。

最后准备应用代码或容器镜像，并记下监听端口、环境变量、密钥、服务账号。本地能跑不代表云端能跑：Cloud Run 要求容器监听 PORT 指定的端口，应用若死写 3000 或 8080，常会启动超时；环境变量、密钥漏配会连不上数据库；服务账号没权限会拉不到私有镜像。别把密钥写进代码、Dockerfile 或仓库，后面用环境变量或 Secret Manager 补上更稳。

整体思路

遇到 Cloud Run 无法部署成功（也就是常搜的 Cloud Run 無法部署成功），先别把红字都当成服务坏了。先判断失败发生在构建、推送镜像、创建修订版本还是启动容器，再用日志缩小范围；不然会在一堆报错里迷路。打开控制台右上角的 Cloud Shell（网页终端），复制下面整段只读命令，不会改坏服务：

# 不急着反复执行 gcloud run deploy
gcloud auth list
gcloud config list
gcloud builds list --limit=5 --format="table(id,status,createTime)"
gcloud builds log "$(gcloud builds list --limit=1 --format='value(id)')"
gcloud run services list --format="table(metadata.name,status.latestCreatedRevisionName,status.latestReadyRevisionName,status.url)"
gcloud logging read 'resource.type="cloud_run_revision" AND severity>=ERROR' --limit=50 --format="table(timestamp,severity,textPayload,jsonPayload.message)"
gcloud services list --enabled --format="value(config.name)" | grep -E "run.googleapis.com|artifactregistry.googleapis.com|cloudbuild.googleapis.com"

读法：构建看 status；推送镜像看 denied 或有没有新镜像；创建修订版本看 latestCreatedRevisionName；启动容器看 latestReadyRevisionName 是否没变、ERROR 日志是否提到 PORT、崩溃、超时。接着按权限、镜像、端口、环境变量、配额这条顺序排查，不急着反复执行部署命令：前面没过，后面会一直报同类错，重复部署只会多造修订版和日志。小白常踩的坑是登录 A 账号却在 B 项目操作、本机镜像能跑但云端架构不对、端口写死 8080、漏了连接串、控制台还停在旧修订版、配额满了也当成启动失败。

每次只改一个配置，并保留报错截图，截图带时间、项目、区域和修订版名，方便对比哪一步让服务恢复；别一次改三处，好了也不知道该记哪条。

详细步骤 1：查看失败日志和当前状态

部署失败别急着改代码，先搞清「哪一步挂了」。日志就是 Cloud Run 给你的检查报告。

打开 GCP 控制台 →「Cloud Run」→ 点进失败的服务，看「日志」和「修订版本」：失败版本带红叉，在日志里找到第一条明确写着 Error / Failed 的报错，整行复制下来。

坑：别盯最后一条，也别被满屏 INFO 带偏，后面多是连锁反应，改错地方白忙半天。

再用命令确认状态，把命令里大写占位符换成自己的（区域如 asia-east1）：

gcloud config set project YOUR_PROJECT_ID
gcloud run services describe YOUR_SERVICE_NAME --region asia-east1

重点看最新修订版本、镜像地址、服务账号、流量状态。为什么？很多时候服务没坏，只是新版本没分到流量、镜像还指向旧包，你却以为没部署上。坑：漏写 --region 会提示找不到服务，不是服务被删了。

若是构建阶段失败，再去「Cloud Build → 历史记录」看构建日志，把错误归三类：代码依赖错误（缺包、版本冲突）、Dockerfile 错误（路径错、基础镜像拉不到）、权限错误（拉镜像或推包被拒）。分好类，才知道该改代码、改 Dockerfile，还是补 IAM 权限。

详细步骤 2：修复最常见的部署配置

部署卡住八成不是代码坏了，而是「谁没权限」或「容器没按规矩启动」。我们按下面顺序补一遍，别跳步。

先补权限。Cloud Build 要读源码、把镜像写进 Artifact Registry；运行时服务账号要读 Secret；你自己的登录账号则要能发布服务。少一个都会报看不懂的 Permission denied。直接复制执行：

export PROJECT_ID=$(gcloud config get-value project)
export REGION="asia-east1"
export SERVICE="my-service"
export NUM=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ME=$(gcloud config get-value account)
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:${NUM}@cloudbuild.gserviceaccount.com" --role="roles/source.reader"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:${NUM}@cloudbuild.gserviceaccount.com" --role="roles/artifactregistry.writer"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:${NUM}-compute@developer.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:${ME}" --role="roles/run.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:${ME}" --role="roles/iam.serviceAccountUser"

再核对镜像和端口。镜像路径里的区域必须和 --region 一致，填成 us-central1 却部署到 asia-east1 是新手最常踩的坑。用下面命令看镜像在不在：

gcloud artifacts docker images list "${REGION}-docker.pkg.dev/${PROJECT_ID}/cloud-run-source-deploy/${SERVICE}" --project=$PROJECT_ID

容器里千万别监听 127.0.0.1，外部流量进不来，要改成 0.0.0.0；端口也别写死 8080，要读环境里的 PORT（Cloud Run 默认给 8080，但以它实际给的为准）。

最后补齐启动参数。环境变量漏一个、内存给太小、超时太短或并发太高，容器常会「刚起来就退出」，日志只剩一行模糊报错。Secret Manager 引用也要去控制台确认已绑到服务、版本是 latest，只建密钥不绑定一样读不到。重新发布时一次带上：

gcloud run deploy $SERVICE 
  --image="${REGION}-docker.pkg.dev/${PROJECT_ID}/cloud-run-source-deploy/${SERVICE}:latest" 
  --region=$REGION --port=8080 
  --set-env-vars="APP_ENV=prod" 
  --memory=512Mi --timeout=300 --concurrency=80 
  --project=$PROJECT_ID

改完去「日志」页看最新一条。还失败也先别改代码，对照上面三项逐个打勾，基本就能定位到 Cloud Run 無法部署成功 的真正原因了。

详细步骤 3：重新部署并观察修订版本

修完上一节的问题后，Cloud Run 无法部署成功时别在控制台乱点。把下面整段复制到同一个终端执行，按提示填值；别关掉终端，否则后面命令会找不到这些变量。填值时注意：项目 ID 不是项目名称，区域和服务名要和原服务一致；镜像带 tag 或 digest，别只写 latest，否则可能没换到新包。

read -r -p "项目 ID：" PROJECT_ID
read -r -p "区域（如 asia-east1）：" REGION
read -r -p "原服务名：" SERVICE
read -r -p "新镜像地址：" IMAGE

gcloud run deploy "$SERVICE" 
  --project "$PROJECT_ID" 
  --region "$REGION" 
  --image "$IMAGE" 
  --quiet

执行后等命令跑完。这条命令会建新修订版本，默认等到它就绪；成功才把 100% 流量切过去。失败时旧版本常还在接流量，所以“网站能打开”不等于修好。再看流量，输出多行时只看下面两处：

gcloud run services describe "$SERVICE" 
  --project "$PROJECT_ID" 
  --region "$REGION" 
  --format="yaml(status.latestReadyRevisionName,status.traffic)"

1. 确认：latestReadyRevisionName 是刚生成的名字，且 traffic 的 percent: 100 指向它，才算成功。
2. 留证：若仍失败，先执行下面命令保存旧日志，再改配置，避免下一次部署覆盖线索；控制台只看最近日志，第一条报错很容易被挤走。

   gcloud logging read "resource.type="cloud_run_revision" AND resource.labels.service_name="$SERVICE"" 
     --project "$PROJECT_ID" 
     --limit 200 
     --format json > cloudrun-old-$(date +%Y%m%d-%H%M%S).json

3. 再修：回到第一条报错继续修，一次只改一项；不要同时改多项配置，例如把端口、环境变量、内存和镜像一起改，否则不知道哪项生效。

生成的文件就是线索。每重试前另存一份，比较第一条错误是否变化，零基础也不容易被新日志绕晕。

验证结果

先别急着改代码。如果之前遇到 Cloud Run 無法部署成功，先确认「真的好了」：在 Cloud Run 服务详情页看到状态为就绪，最新修订版本能接收 100% 流量。为什么看流量？构建成功不等于线上成功，流量若还留在旧版本，你访问的仍是旧代码。坑：看错项目、区域，或只看到绿色勾就以为更新完成。

1. 接着确认访问服务网址能返回预期页面或接口结果。复制详情页网址，或在 Cloud Shell 执行下面整段，按提示输入服务名和区域；不知道填什么，就从详情页标题和地址栏复制，别凭记忆手打。状态码正常，才算用户侧打通。

2. 再看最近日志，确认日志中没有反复重启、权限拒绝和端口绑定失败。401/403 可能只是开了身份验证或没给调用者权限；容器要监听 Cloud Run 给的 PORT，并绑定 0.0.0.0，写成 127.0.0.1 很容易失败。坑：别只看构建日志，运行日志才反映启动后的真实情况。

3. 最后用 gcloud run services describe 复查镜像、端口、环境变量和服务账号，确认与预期一致。命令输出较长，重点找 image、containerPort、env、serviceAccountName；若查不到，多半是项目或区域选错。坑：环境变量改了却没生成新修订版本、服务账号少权限，都会出现「看起来好了但用不了」。

read -r -p "服务名: " S; read -r -p "区域(如 asia-east1): " R
gcloud run services describe "$S" --region "$R" --format=yaml
URL=$(gcloud run services describe "$S" --region "$R" --format='value(status.url)'); curl -i "$URL"
gcloud logging read "resource.type="cloud_run_revision" AND resource.labels.service_name="$S" AND resource.labels.location="$R"" --limit=100 --format='value(timestamp,severity,textPayload,jsonPayload.message)'

常见坑与解决办法

遇到「Cloud Run 無法部署成功」，先复制执行下面一整段，把配置、API、日志、角色、密钥线索拉齐。

P=$(gcloud config get-value project)
N=$(gcloud projects describe "$P" --format='value(projectNumber)')
gcloud config list
gcloud config get-value project
gcloud config get-value run/region
gcloud artifacts repositories list --project="$P" --format='table(name,format)'
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com --project="$P"
gcloud builds log "$(gcloud builds list --limit=1 --format='value(id)' --project="$P")" --project="$P"
gcloud logging read 'resource.type="cloud_run_revision" AND severity>=ERROR' --limit=50 --project="$P" --format='table(timestamp,textPayload)'
for R in roles/secretmanager.secretAccessor roles/artifactregistry.reader roles/logging.logWriter; do gcloud projects add-iam-policy-binding "$P" --member="serviceAccount:$N-compute@developer.gserviceaccount.com" --role="$R"; done
gcloud secrets list --project="$P"

1. 只看失败页。先从 Cloud Run 和 Cloud Build 日志找第一条根因；最后一行多是结果，别只看最后一行。
2. 只听本机。写死 127.0.0.1 或固定端口，请求进不来；改监听 0.0.0.0，端口读 PORT 环境变量。小白常写成小写 port，改完也要重部署。
3. 权限或密钥没绑好。Permission denied、Secret not found 多因服务账号权限不足、Secret Manager 没授权、密钥未绑定或环境变量名称写错。上面已补齐 IAM 角色；再核对 Secret Manager 授权、名称大小写，自定义账号也要补。
4. 项目区域选错。忘记启用 API、选错项目或区域，镜像会像“消失”。部署前核对 gcloud config、项目 ID、区域、镜像仓库位置；多项目别凭记忆判断。

常见问题（FAQ）

Cloud Run 部署失败先看哪里？

先看 Cloud Run 日志和 Cloud Build 日志，按报错定位权限、镜像或端口问题。

没有容器镜像可以部署吗？

可以从源码部署，但要确保构建成功，并给服务账号开通读写镜像仓库的权限。

本地能跑，云端启动失败怎么办？

重点检查是否监听 0.0.0.0、读取 PORT 环境变量，以及密钥和超时配置。