Cloud Run 的容器运行约定
Cloud Run 可以运行任何符合几条基本约定的容器。Google 文档说明，请求默认发送到端口 8080，PORT 环境变量会设置在入口容器上，容器“必须在 0.0.0.0 上监听请求”，且“不应在 127.0.0.1 上监听”。文档还说明 Cloud Run“明确支持 Linux x86_64 ABI 格式”，多架构镜像必须包含 linux/amd64。
其中两条容易让 Mac 开发者踩坑：绑定 localhost 的应用在本地终端中正常，却会在 Cloud Run 上失败；而在 Apple 芯片 上原生构建的镜像是 arm64。在本地测试实际容器，可以在部署前发现这两个问题。
在 Apple 芯片 上本地测试 Cloud Run 服务
- 在 $PORT 和 0.0.0.0 上监听。 让服务器读取
PORT环境变量（Cloud Run 默认向 8080 发送请求），并绑定0.0.0.0，而非127.0.0.1。 - 为 linux/amd64 构建。 运行
docker buildx build --platform linux/amd64 --load -t my-service .。Cloud Run 支持 Linux x86_64 ABI，因此在 Mac 上原生构建的 arm64 镜像目标架构不符。 - 按 Cloud Run 的方式运行。 运行
docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service。Oxcart 通过 Rosetta 运行 amd64 镜像。 - 调用服务。 运行
curl localhost:8080。要检查 PORT 的处理方式，请用-e PORT=9090 -p 9090:9090启动第二个实例。 - 推送到 Artifact Registry。 执行一次
gcloud auth configure-docker REGION-docker.pkg.dev，然后将镜像标记为REGION-docker.pkg.dev/PROJECT/REPO/my-service:TAG，再用docker push推送。
我们在 Oxcart 上运行了什么
一个绑定 $PORT 的小型 Python 服务，分别使用不同端口运行两次，再加上 Google 自己的示例镜像：
docker run -d -e PORT=8080 -p 18081:8080 my-service
docker run -d -e PORT=9090 -p 18090:9090 my-service
curl localhost:18081 # hello from PORT=8080
curl localhost:18090 # hello from PORT=9090
docker run -d -e PORT=8080 -p 8081:8080 us-docker.pkg.dev/cloudrun/container/hello
docker image inspect us-docker.pkg.dev/cloudrun/container/hello --format '{{.Os}}/{{.Architecture}}'
# linux/amd64
curl localhost:8081 # "It's running!"Google 的示例是仅含 amd64 的镜像；Oxcart 拉取后直接通过 Rosetta 运行，无需额外参数。对于自己构建的仅含 amd64 的镜像，执行 docker run 时也请传入 --platform linux/amd64：在我们的测试中，只有指定平台后才能找到本地构建的 amd64 镜像。
在 Apple 芯片 上构建 linux/amd64 镜像
# Cloud Run target: amd64
docker buildx build --platform linux/amd64 --load -t my-service:amd64 .
# Both architectures in the local image store (runs locally either way)
docker buildx build --platform linux/amd64,linux/arm64 -t my-service:multi .Oxcart 的默认构建器同时列出 linux/amd64 和 linux/arm64，多平台构建可以在本地完成，两个变体都能运行。Oxcart 不支持推送多平台镜像，因此部署到 Cloud Run 时，请推送 amd64 标签，因为它运行的就是这个变体。构建很快：小型本地构建上下文无缓存时为 341 ms，有缓存时为 121 ms，是我们测试的三个运行时中最快的。
推送到 Artifact Registry 并部署
gcloud auth configure-docker us-central1-docker.pkg.dev
docker tag my-service:amd64 us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0
docker push us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0
gcloud run deploy my-service \
--image us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0 --region us-central1使用 Compose 运行依赖服务
Cloud Run 服务通常需要访问数据库、缓存或其他服务。使用 Compose 将它们一同运行，在服务环境中设置 PORT，并通过健康检查控制启动顺序：
services:
api:
build: .
platform: linux/amd64
environment:
PORT: "8080"
REDIS_URL: redis://cache:6379
ports: ["8080:8080"]
depends_on:
cache:
condition: service_healthy
cache:
image: redis:7-alpine
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
retries: 30缓存通过健康检查且 API 启动后，docker compose up -d --wait 才会返回。Apple 芯片 上的 Compose 指南详细介绍了健康检查、amd64 镜像和端口。
Mac 上的端口
与 Docker 默认行为一样，发布的端口监听 Mac 的所有网络接口。如果另一个 Mac 应用已在 127.0.0.1:8080 上监听，访问 localhost:8080 可能到达该应用，而不是容器。因此，请选择空闲的宿主机端口（-p 18080:8080），同时让 PORT 保持 Cloud Run 设置的值。Oxcart 的 Ports 视图会在容器旁显示 Mac 上所有监听服务，并解释容器端口为何不响应，例如容器内的服务器绑定了 127.0.0.1；这也是 Cloud Run 会拒绝的错误。参阅Mac 上的容器网络。
常见问题
如何在 Mac 上本地运行 Cloud Run 服务？
设置 PORT 变量并发布端口后运行容器：docker run -e PORT=8080 -p 8080:8080 IMAGE。这是 Google 文档提供的 Docker 本地测试方法。在 Oxcart 上，我们使用自己的镜像在 8080 和 9090 端口验证过，也使用 Google 的 us-docker.pkg.dev/cloudrun/container/hello 示例验证过。
为什么在 Apple 芯片 上构建的镜像部署到 Cloud Run 会失败？
Google 文档说明，Cloud Run 支持 Linux x86_64 ABI，多架构镜像必须包含 linux/amd64。在 Apple 芯片 Mac 上直接执行 docker build 会生成 arm64 镜像。请使用 --platform linux/amd64 构建。
部署前能在 Mac 上运行 amd64 镜像吗？
可以。Oxcart 通过 Rosetta 运行 linux/amd64 镜像。运行本地自行构建的仅含 amd64 的镜像时，请传入 --platform linux/amd64；在我们的测试中，拉取的 amd64 镜像（如 Google 的 hello 示例）不带此参数也能运行。
容器本地能运行，但 Cloud Run 提示未能监听端口，为什么？
最常见的原因是绑定了 127.0.0.1 或硬编码端口。Cloud Run 的容器运行约定要求容器在 0.0.0.0 上监听 PORT 指定的端口。请在本地用非默认 PORT（如 9090）测试，以发现硬编码端口。
需要 gcloud beta code dev 或 Cloud Code 吗？
不需要，它们是可选项。Google 列出的本地测试方式包括普通 Docker、可访问 Google Cloud 的 Docker、Cloud Code 模拟器和 gcloud beta code dev。在 Oxcart 上使用 Docker，可以直接测试镜像及其 PORT 处理方式。gcloud beta code dev 则通过 minikube 或现有 Kubernetes 上下文提供基于 Kubernetes 的开发流程；需要这种集成时再选择它。
如何让本地容器访问 Google Cloud API？
按照 Google 文档中“可访问 Google Cloud 的 Docker”的方式挂载凭据，通常通过挂载文件和 GOOGLE_APPLICATION_CREDENTIALS 传入应用默认凭据（Application Default Credentials）。Oxcart 容器的出站连接由 Mac 建立，因此会使用你的 VPN 和 DNS。
来源与方法
- 示例测试环境：Oxcart 0.1.2，Mac17,14，macOS 27.2，2026-10-10（PORT 设为 8080 和 9090、Google hello 示例以 linux/amd64 运行、Buildx 单平台与多平台构建）。
- Cloud Run 容器运行约定（端口、0.0.0.0、x86_64）：https://docs.cloud.google.com/run/docs/container-contract。本地测试选项：https://docs.cloud.google.com/run/docs/testing/local 和 https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev。核查日期：2026-10-10。
- 构建速度：Oxcart 0.1.2，2026-10-10，Apple M5 Max，8 个 CPU 和 12 GiB，取五次采样的中位数；其他运行时于同一天较早时段，在同一台 Mac 上使用相同测量工具及 docker 29.4 客户端测量。