Remotion LabRemotion Lab
›Cloud Run›Cloud Run 疑難排解

Cloud Run 疑難排解

Remotion Cloud Run 常見問題排解指南，包含錯誤訊息說明、偵錯步驟與日誌查看方式。

Cloud Run 疑難排解

本文整理在使用 Remotion Cloud Run 時常見的問題與解決方法。

查看渲染日誌

日誌是診斷問題的第一步。

使用 GCP Console 查看

  1. 前往 Cloud Logging
  2. 在篩選器中輸入：
resource.type="cloud_run_revision"
resource.labels.service_name="remotion-render-4-0-0"

使用 CLI 查看

gcloud logging read \
  'resource.type="cloud_run_revision"' \
  --project=YOUR_PROJECT_ID \
  --limit=50 \
  --format=json

使用 Node.js API 查看

import { getLogs } from "@remotion/cloudrun";
 
const logs = await getLogs({
  region: "asia-east1",
  renderId: "abc123",
});
 
console.log(logs);

常見錯誤與解決方法

錯誤：Permission denied / 權限不足

症狀：

Error: 7 PERMISSION_DENIED: Permission 'run.services.create' denied on resource

原因： 服務帳戶缺少必要的 IAM 角色。

解決方法：

# 1. 驗證目前權限
npx remotion cloudrun permissions
 
# 2. 補充缺少的角色
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:remotion-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.admin"

錯誤：Service not found

症狀：

Error: Service remotion-render-4-0-0 not found in region asia-east1

原因： 服務尚未部署，或部署在其他區域。

解決方法：

# 列出所有服務確認名稱與區域
npx remotion cloudrun services ls
 
# 若服務不存在，重新部署
npx remotion cloudrun services deploy --region=asia-east1

錯誤：版本不符

症狀：

Error: The Cloud Run service version (4.0.0) does not match the local package version (4.1.0).

原因： 本機 @remotion/cloudrun 升級後，未重新部署 Cloud Run 服務。

解決方法：

# 刪除舊版服務
npx remotion cloudrun services rm remotion-render-4-0-0 --region=asia-east1
 
# 部署新版本
npx remotion cloudrun services deploy --region=asia-east1

錯誤：Timeout / 渲染超時

症狀：

Error: Cloud Run request timed out after 300 seconds

原因： 影片過長或 Cloud Run 服務的逾時設定不足。

解決方法：

# 重新部署服務，增加逾時時間（最大 3600 秒）
npx remotion cloudrun services deploy \
  --region=asia-east1 \
  --timeout=3600

或在渲染時調整：

const result = await renderMediaOnCloudrun({
  region: "asia-east1",
  serviceName: "remotion-render-4-0-0",
  serveUrl: "https://storage.googleapis.com/...",
  composition: "LongVideo",
  codec: "h264",
  // 增加單幀逾時時間
  timeoutInMilliseconds: 60000,
});

錯誤：記憶體不足（OOM）

症狀：

Error: Cloud Run instance was terminated due to memory limit: 8Gi

或 Cloud Logging 中出現 SIGKILL / container terminated.

原因： 影片使用了大量記憶體（高解析度、複雜動畫、大量圖片）。

解決方法：

重新部署服務，增加記憶體上限：

npx remotion cloudrun services deploy \
  --region=asia-east1 \
  --memory=16Gi \
  --cpu=8

錯誤：serveUrl 無法存取

症狀：

Error: Failed to load site from URL: 403 Forbidden

原因： Cloud Storage Bucket 或站台設定不允許 Cloud Run 服務讀取。

解決方法：

確認 Bucket 設定允許服務帳戶讀取：

gsutil iam ch \
  serviceAccount:remotion-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com:roles/storage.objectViewer \
  gs://your-bucket-name

或重新上傳站台：

npx remotion cloudrun sites create src/index.ts \
  --site-name=my-site \
  --region=asia-east1

錯誤：Chromium 啟動失敗

症狀：

Error: Failed to launch the browser process

原因： Cloud Run 服務的記憶體不足以啟動 Chromium，或映像版本問題。

解決方法：

# 1. 增加最小記憶體至 2Gi
npx remotion cloudrun services deploy \
  --region=asia-east1 \
  --memory=4Gi
 
# 2. 確認使用最新版本的映像
npx remotion cloudrun services deploy --region=asia-east1

錯誤：Billing not enabled

症狀：

Error: Billing account for project not found. Billing must be enabled for activation of service(s)

原因： GCP 專案尚未啟用帳單。

解決方法：

前往 Cloud Console 帳單頁面 建立並連結帳單帳戶。

錯誤：環境變數格式問題

症狀：

Error: Could not parse private key. Make sure REMOTION_GCP_PRIVATE_KEY is formatted correctly.

原因： REMOTION_GCP_PRIVATE_KEY 中的換行字元格式不正確。

解決方法：

確認 .env 中私鑰格式如下（換行用 \n 表示，整個值用引號包覆）：

REMOTION_GCP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"

偵錯工具

檢查服務狀態

gcloud run services describe remotion-render-4-0-0 \
  --region=asia-east1 \
  --format=yaml

查看最近的錯誤日誌

gcloud logging read \
  'resource.type="cloud_run_revision" severity>=ERROR' \
  --project=YOUR_PROJECT_ID \
  --freshness=1h \
  --limit=20

測試服務健康狀態

# 取得服務 URL
SERVICE_URL=$(gcloud run services describe remotion-render-4-0-0 \
  --region=asia-east1 \
  --format='value(status.url)')
 
# 呼叫健康檢查端點
curl "${SERVICE_URL}/info"

問題排查流程

渲染失敗
  ↓
1. 確認服務版本與本機版本一致
      ↓ 不一致 → 重新部署服務
   一致 ↓
2. 查看 Cloud Logging 中的錯誤訊息
      ↓
3. 對照本文的常見錯誤清單
      ↓
4. 確認 IAM 權限（npx remotion cloudrun permissions）
      ↓
5. 確認資源配置（CPU、記憶體、逾時）是否足夠
      ↓
6. 在較小的 Composition 上重現問題進行隔離

小結

  • 版本不符是最常見的問題，升級 Remotion 後務必重新部署服務
  • 使用 Cloud Logging 查看詳細錯誤訊息
  • 記憶體不足和逾時可透過重新部署服務調整資源配置解決
  • npx remotion cloudrun permissions 可快速診斷 IAM 問題

另請參閱