# @cosmicdrift/kumiko-renderer-puppeteer-client 中文文档

规范地址：https://npmcn.com/package/%40cosmicdrift/kumiko-renderer-puppeteer-client/

版本：0\.419\.0
npm 元数据更新时间：2026-11-10T16:29:52.213Z
中文译文更新时间：2026-11-10T20:12:44.621Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cosmicdrift/kumiko-renderer-puppeteer-client
原文对照：https://npmcn.com/package/%40cosmicdrift/kumiko-renderer-puppeteer-client/?lang=original
项目主页：https://kumiko.rocks/
源码仓库：https://github.com/CosmicDriftGameStudio/kumiko-framework

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

- 包体积（解压后）：106 kB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-16T19:05:10.168Z
- 最新版本发布：2026-11-10T16:29:51.861Z
- 近 30 天下载量：13724（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

Render-Foundation插件:用于傀儡-服务的HTTP客户端(PDF + 图像快照通过远程浏览器).

## 安装

```sh
npm install @cosmicdrift/kumiko-renderer-puppeteer-client
```

也可以使用：`pnpm add @cosmicdrift/kumiko-renderer-puppeteer-client`、`yarn add @cosmicdrift/kumiko-renderer-puppeteer-client`、`bun add @cosmicdrift/kumiko-renderer-puppeteer-client`

## README

# 渲染器-puppeteer-客户端

插件用于 `renderer-foundation`. 招标人 `kind=["document-pdf", "image-snapshot"]` 通过 HTTP 呼叫请求 `puppeteer-service` (在 `apps/puppeteer-service` )),该存储器中.

## 建筑

```
Caller (e.g. Solon NKA-PDF-Generator)
   │
   │ const renderer = foundation.createRendererForTenant({ tenantId, kind: "document-pdf" })
   │ await renderer.render({ kind: "document-pdf", payload: { content: "<html>…" } }, ctx)
   ▼
renderer-puppeteer-client (THIS package)
   │
   │ POST {PUPPETEER_SERVICE_URL}/render
   │ Authorization: Bearer {PUPPETEER_AUTH_TOKEN}
   │ Retry: 5xx + network-error (exponential backoff)
   ▼
puppeteer-service (separate app, K8s deployment)
   │
   │ Launches Puppeteer browser, renders HTML
   ▼
{kind: "document-pdf", pdfBytes, ...}
```

## 挂载

```typescript
import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";

const features = [
  createRendererFoundationFeature(),
  createRendererPuppeteerClientFeature(),
  // additional renderer plugins (renderer-mail-html, …)
];

// In createKumikoApp's extraContext:
extraContext: ({ db, registry }) => ({
  rendererFoundation: createRendererFoundationApi(collectRendererPlugins(registry)),
});
```

## 配置( env vars)

App-wide,通过 K8s Secret + ConfigMap 设置 :

| 瓦尔 | 默认 | 说明 |
| --- | --- | --- |
| `PUPPETEER_SERVICE_URL` | `http://puppeteer-service:3000` | 服务的内部集群 URL |
| `PUPPETEER_AUTH_TOKEN` | **所需经费** | 共享秘密( QQ16 字符, 匹配服务) |
| `PUPPETEER_CLIENT_TIMEOUT_MS` | `60000` | 按请求暂停(客户方) |
| `PUPPETEER_CLIENT_MAX_RETRIES` | `3` | 5xx/ 网络错误的重试次数 |

**每个租户?** 现 **没有**所有租户都使用同样的服务。 如有实际需要,将增加通过配置包覆盖的租户,例如企业租户专用的Puppeteer池.

## 重试策略

| 回应 | 行动 |
| --- | --- |
| `2xx` | 成功, 返回字节 |
| `4xx` (验证、认证、413) | **无重试**返回时 `RendererError("invalid_payload")` 马上 |
| `5xx` (回复出错,服务崩溃) | 以指数回放( 200ms × 2^ 尝试) + ± 50% 焦距重试 |
| 网络错误(ECONNREFUSED,超时) | 重试为 5xx |

之后 `PUPPETEER_CLIENT_MAX_RETRIES` 已用尽 : `RendererError("other")` 带有原始错误消息.

## 调用模式

```typescript
import { requireRendererFoundation } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";

async function generatePdf(ctx, tenantId, htmlContent) {
  const foundation = requireRendererFoundation(ctx, "generatePdf");
  const renderer = foundation.createRendererForTenant({ tenantId, kind: "document-pdf" });

  const result = await renderer.render(
    {
      kind: "document-pdf",
      payload: { content: htmlContent },
      options: { format: "A4", marginMm: { top: 15, bottom: 15 } },
    },
    { db: ctx.db, registry: ctx.registry, tenantId },
  );

  if (result.kind !== "document-pdf") throw new Error("unexpected kind");
  return result.pdfBytes; // → S3 upload or directly to the caller
}
```

## 测试

-   **15个单元测试** (配置+HTTP客户端+提供+合同). 没有真正的网络呼叫, 获取嘲笑通过 `vi.stubGlobal`。 。 。 .
-   **没有实际服务的整合测试**。服务堆栈要求傀儡服务在 URL 运行,这是 E2E 设置(第7步) 。 这里,只有HTTP层的单位覆盖.

## 范围外

-   HTML sanitization: 呼叫者提供可信赖的 HTML( 从模板解析器和租户范围化)
-   文件存储: 响应总是包含内含字节, 必要时, 调用者会坚持使用 S3
-   特定租户的URL:目前是全应用的,可能以后通过一个配置包

## 常见问题

### @cosmicdrift/kumiko-renderer-puppeteer-client 是什么？

Render-Foundation插件:用于傀儡-服务的HTTP客户端\(PDF \+ 图像快照通过远程浏览器\)\.

### 如何安装 @cosmicdrift/kumiko-renderer-puppeteer-client？

在项目目录运行 npm install @cosmicdrift/kumiko-renderer-puppeteer-client，或使用 pnpm add / yarn add / bun add。

### @cosmicdrift/kumiko-renderer-puppeteer-client 支持 TypeScript 吗？

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

### @cosmicdrift/kumiko-renderer-puppeteer-client 支持 ESM 还是 CommonJS？

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

### @cosmicdrift/kumiko-renderer-puppeteer-client 可以商用吗？

@cosmicdrift/kumiko-renderer-puppeteer-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cosmicdrift/kumiko-renderer-puppeteer-client 的下载量有多少？

根据 npm 官方下载统计，@cosmicdrift/kumiko-renderer-puppeteer-client 在 2026/10/11 – 2026/11/09 这 30 天内被下载 13,724 次，日均约 457 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cosmicdrift/kumiko-renderer-puppeteer-client 还在维护吗？

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