# @hyperframes/gcp-cloud-run 中文文档

规范地址：https://npmcn.com/package/%40hyperframes/gcp-cloud-run/

版本：0\.8\.226
npm 元数据更新时间：2026-11-01T06:33:05.801Z
中文译文更新时间：2026-11-01T10:16:36.914Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hyperframes/gcp-cloud-run
原文对照：https://npmcn.com/package/%40hyperframes/gcp-cloud-run/?lang=original
项目主页：https://github.com/heygen-com/hyperframes#readme
源码仓库：https://github.com/heygen-com/hyperframes

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：197 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：7 个
- 首次发布：2026-06-07T21:53:25.754Z
- 最新版本发布：2026-11-01T06:33:05.489Z
- 已发布版本数：382（近 12 个月 382 个）

## 中文简介

谷歌HyperFrames分布式渲染的Cloud Run +工作流适配器——请求处理程序、客户端SDK和Terraform模块。

## 安装

```sh
npm install @hyperframes/gcp-cloud-run
```

也可以使用：`pnpm add @hyperframes/gcp-cloud-run`、`yarn add @hyperframes/gcp-cloud-run`、`bun add @hyperframes/gcp-cloud-run`

## README

# @hyperframes / gcp-cloud-run

谷歌云运行+云工作流适配器的超帧分布 呈现。OSS呈现原语(`plan` → `renderChunk` × n→ `assemble`)是本地文件路径上的纯函数；这个包裹是 在谷歌Cloud上运行它们的部署、编排和存储胶水 的GCP对应 [`@hyperframes/aws-lambda`](https://npmcn.com/package/%40hyperframes/aws-lambda).

两面一包：

-   **服务器端处理程序** （`./server`)——一个云运行的HTTP服务 分派 `plan` / `renderChunk` / `assemble` 在请求主体的 `Action` 字段，桥接GCS↔每个OSS周围的容器的文件系统 原始的。这是捆绑的 `Dockerfile` 运行。
-   **客户端SDK** （`./sdk`) - - - `renderToCloudRun`， `getRenderProgress`， `deploySite`， `validateDistributedRenderConfig`, `computeRenderCost`. 从Node进程（CI、CLI、应用程序后端）调用它们来驱动已部署的 堆栈不写GCS /工作流样板。

包裹是 **不** 的依赖 `@hyperframes/producer`;安装它 分开。

## 体系结构

```
GCS bucket  ←→  Cloud Run service (plan / renderChunk / assemble)
                     ▲
                     │ OIDC-authenticated http.post, one per step
                     │
                Cloud Workflows  (Plan → parallel RenderChunk → Assemble)
```

-   **计划** 下载项目压缩包并发布遗留版本v1 planDir tarball或v2清单加上内容寻址的工件。
-   **RenderChunk** 并行运行 `for` 循环在工作流程中，呈扇形展开 直到计划的块计数。每次调用呈现一个块并上传 它。
-   **组装** 下载每个块和音频，缝合最终 可交付，并上传。

每一步都是 `POST` 到同一个Cloud Run URL使用不同的 `Action`. 工作流累积每个步骤的小结果体并返回 `{ Plan, Chunks, Assemble }` 所以 `getRenderProgress` 可以读取帧总数和 每一步成功的持续时间。

### 规划运输选择

Plan v2是新渲染的默认版本。当 `planProtocol` 省略了, `renderToCloudRun` 发送显式的 `PlanProtocol: "v2"` 所以SDK和 部署的工作流同意：

```ts
await renderToCloudRun({
  // ...project, bucket, workflow, service, and config...
});
```

V2始终使用单独的清单和内容寻址的工件定位器 工作流。未知协议和完整性失败失败关闭；呈现 永远不要混合v1和v2工件。

作为已弃用的兼容性，单片v1传输仍然可用 通过 `planProtocol: "v1"` 明确。

#### 更新订单

从相同的new中重新部署Cloud Run映像和Cloud工作流定义 在升级调用 `renderToCloudRun`。暂停新的渲染并消耗活动的工作流执行 在基础设施更新期间。较旧的工作流可以将省略默认为v1 或者缺少v2分支，而新的SDK发送显式的v2。如果基础设施 不能先重新部署，保留以前的SDK版本或通过 `planProtocol: "v1"` 直到Terraform/工作流重新部署完成 完成了。

## Chrome运行时

不像Lambda适配器，它与250mb的ZIP上限作斗争 解压缩 `@sparticuz/chromium` 成 `/tmp` 在运行时-云运行运行一个 容器的形象。这个 `Dockerfile` 安装相同的固定 `chrome-headless-shell` 生成渲染器使用的构建和字体设置 固定路径，并导出 `HYPERFRAMES_CHROME_PATH`。CDP-level `BeginFrame` 支持的是二进制/运行时功能，因此映像构建启动它 需要启用+预热+ png返回 `HeadlessExperimental.beginFrame` 探测器通过。端到端烟雾 要求每个块报告有效 `CaptureMode: "beginframe"`,这 从构建时打包中单独捕获运行时回退。没有 运行时解压步骤，没有封装上限。

## 部署

这个 `terraform/` 模块提供一切：GCS渲染桶， 云运行服务，云工作流定义，两个最小权限 服务帐户（服务读取/写入桶；工作流调用） 服务)，以及一个逃跑请求警报。

```bash
# 1. Build + push the image (Cloud Build or local docker).
gcloud builds submit . \
  --tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG

# 2. Apply the module.
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
  -var project_id=PROJECT \
  -var region=us-central1 \
  -var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
```

起程拓殖输出 `render_bucket_name`， `service_url`， `workflow_name`, `region` -将它们直接传递到SDK中。

## 使用SDK

```ts
import { renderToCloudRun, getRenderProgress } from "@hyperframes/gcp-cloud-run/sdk";

const handle = await renderToCloudRun({
  projectDir: "./my-composition",
  config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
  bucketName: "hyperframes-render-my-project", // from terraform output
  projectId: "my-project",
  location: "us-central1",
  workflowId: "hyperframes-render",
  serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});

// Poll until done.
let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
  await new Promise((r) => setTimeout(r, 5000));
  progress = await getRenderProgress({ executionName: handle.executionName });
}
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
```

`deploySite` 在传递时隐式调用 `projectDir`;叫它 预先上传一次，然后重复使用 `siteHandle` 在许多渲染中 （例如，个性化的模板批次）。

## 运行测试

```bash
bun test          # unit tests over an in-memory GCS double — no network
bun run typecheck
```

现场端到端烟雾（构建图像→地形应用→渲染灯具） 通过工作流→psnr→比较→破坏)生命 `examples/gcp-cloud-run/scripts/smoke.sh` 并且需要一个GCP项目 计费启用。

## 前方还有什么

-   **飞行中的每块进度。** `getRenderProgress` 报告粗 `running` 进展和成功的确切数字。阅读云 工作流的步进API将在渲染时给出每个块的进度 在飞行中；作为后续跟踪。
-   **云运行作业/ Firebase函数变体。** 第一个版本 目标是云运行服务+工作流（最接近Lambda +的模拟） 步骤功能)。相同的处理程序在云运行作业下不变地运行； 只有业务流程触发器不同。

## 常见问题

### @hyperframes/gcp-cloud-run 是什么？

谷歌HyperFrames分布式渲染的Cloud Run \+工作流适配器——请求处理程序、客户端SDK和Terraform模块。

### 如何安装 @hyperframes/gcp-cloud-run？

在项目目录运行 npm install @hyperframes/gcp-cloud-run，或使用 pnpm add / yarn add / bun add。

### @hyperframes/gcp-cloud-run 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @hyperframes/gcp-cloud-run 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hyperframes/gcp-cloud-run 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @hyperframes/gcp-cloud-run 可以商用吗？

@hyperframes/gcp-cloud-run 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @hyperframes/gcp-cloud-run 还在维护吗？

最新版本 0\.8\.226 发布于 2026/11/01（2 天前）；至今共发布 382 个版本，其中过去 12 个月发布了 382 个；首次发布于 2026/06/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。