# @happyvertical/comfyui 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/comfyui/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:01:04.691Z
中文译文更新时间：2026-11-17T14:19:36.235Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/comfyui
原文对照：https://npmcn.com/package/%40happyvertical/comfyui/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/comfyui#readme
源码仓库：https://github.com/happyvertical/sdk

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

- 包体积（解压后）：73 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-23T08:14:11.255Z
- 最新版本发布：2026-11-17T00:01:04.407Z
- 近 30 天下载量：5350（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：132（近 12 个月 132 个）

## 中文简介

ComfyUI API 客户端,用于工作流程管弦和视频生成

## 安装

```sh
npm install @happyvertical/comfyui
```

也可以使用：`pnpm add @happyvertical/comfyui`、`yarn add @happyvertical/comfyui`、`bun add @happyvertical/comfyui`

## README

* * *

## 代码: comfyui 标题 : "@happyvertical/comfyui: ComfyUI API 客户端" 侧边栏 标签: "@happyvertical/comfyui" 侧边栏( p): 10

# @ happyvertical/comfyui (英语)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

一个基于WebSocket的客户端,用于"HE SDK"中的ComfyUI工作流程管弦和视频生成.

## 概览

这个 `@happyvertical/comfyui` 软件包为通过WebSocket与ComfyUI服务器交互提供了TypeScript客户端. 它支持工作流程执行,进度监测和输出下载AI动力图像和视频生成管道.

## 特征

-   **WebSocket 连接**: 与ComfyUI服务器的实时通信
-   **工作流程执行**: 排队并执行ComfyUI工作流程
-   **进展监测**: 跟踪详细事件的执行进展情况
-   **参数喷出**: 动态向工作流程节点注入值
-   **输出下载**: 获取生成的图像和视频
-   **队列管理**: 监测和管理执行队列
-   **系统Stats**: 查询服务器状态和能力
-   **文件上传**: 为工作流程输入上传图像和其他文件

## 安装

```bash
# Install with bun (recommended)
bun add @happyvertical/comfyui

# Or with npm
npm install @happyvertical/comfyui

# Or with pnpm
pnpm add @happyvertical/comfyui
```

## 快速启动

### 基本用途

```typescript
import { ComfyUIClient, injectWorkflowParams } from '@happyvertical/comfyui';

// Create client
const client = new ComfyUIClient({
  url: 'http://localhost:8188',
});

// Connect to server
await client.connect();

// Load and modify workflow
const workflow = JSON.parse(fs.readFileSync('workflow.json', 'utf-8'));
const modifiedWorkflow = injectWorkflowParams(
  workflow,
  {
    seedImage: '3',
    prompt: '6',
  },
  {
    seedImage: 'input/anchor.png',
    prompt: 'professional news anchor speaking',
  }
);

// Queue prompt and wait for completion
const result = await client.queuePrompt(modifiedWorkflow);
const history = await client.waitForCompletion(result.promptId);

// Download output
const output = history.outputs['SaveVideo'];
if (output?.videos?.[0]) {
  const video = await client.downloadOutput(output.videos[0].filename);
  fs.writeFileSync('output.mp4', video);
}

await client.disconnect();
```

### 进展跟踪

```typescript
const history = await client.waitForCompletion(promptId, {
  onProgress: (event) => {
    switch (event.type) {
      case 'progress':
        console.log(`Progress: ${event.value}/${event.max}`);
        break;
      case 'executing':
        console.log(`Executing node: ${event.node}`);
        break;
      case 'execution_cached':
        console.log(`Cached nodes: ${event.nodes.join(', ')}`);
        break;
    }
  },
});
```

### 文件上传

```typescript
// Upload image for workflow input
const imageBuffer = fs.readFileSync('input.png');
const uploadResult = await client.uploadImage(imageBuffer, 'input.png');

console.log(`Uploaded: ${uploadResult.name}`);
```

### 系统状态

```typescript
// Get system stats
const stats = await client.getSystemStats();
console.log(`Queue: ${stats.queue.running}/${stats.queue.pending}`);

// Get queue status
const queue = await client.getQueueStatus();
console.log(`Running: ${queue.running.length}, Pending: ${queue.pending.length}`);
```

## API 参考

### 舒适度

与ComfyUI服务器互动的主要客户类.

#### 构造器

```typescript
new ComfyUIClient(options: ComfyUIClientOptions)
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | \- 说吧 | ComfyUI 服务器 URL(例如, `http://localhost:8188`(中文(简体) ) |
| `clientId` | `string` | 自动生成 | 唯一客户端标识符 |
| `timeout` | `number` | `600000` | 请求超时( 毫秒) |

#### 方法

| 方法 | 说明 |
| --- | --- |
| `connect()` | 建立 WebSocket 连接 |
| `disconnect()` | 关闭 WebSocket 连接 |
| `queuePrompt(workflow)` | 列出执行工作流程 |
| `waitForCompletion(promptId, options?)` | 等待进度跟踪迅速完成 |
| `getHistory(promptId)` | 获取行刑记录以提示 |
| `getQueueStatus()` | 获取当前队列状态 |
| `getSystemStats()` | 获取服务器系统统计 |
| `uploadImage(buffer, filename, options?)` | 上传图像文件 |
| `downloadOutput(filename, subfolder?, type?)` | 下载已生成的输出文件 |
| `interruptExecution()` | 中断当前执行 |
| `clearQueue()` | 清除所有待定的队列项目 |

### 注入WorkflowParams 图像

用于向工作流程节点注入动态值的功能.

```typescript
function injectWorkflowParams(
  workflow: ComfyWorkflow,
  nodeMapping: NodeMapping,
  values: Record<string, unknown>
): ComfyWorkflow
```

#### 参数

-   `workflow` - ComfyUI工作流程JSON
-   `nodeMapping` - 将参数名称映射到节点ID(例如, `{ seedImage: '3' }`(中文(简体) )
-   `values` - 注入值(例如, `{ seedImage: 'path/to/image.png' }`(中文(简体) )

## 类型

```typescript
interface ComfyUIClientOptions {
  url: string;
  clientId?: string;
  timeout?: number;
}

interface PromptResult {
  promptId: string;
  number: number;
  nodeErrors?: Record<string, unknown>;
}

interface HistoryEntry {
  promptId: string;
  outputs: Record<string, NodeOutput>;
  status: { completed: boolean; messages?: unknown[] };
}

interface ProgressEvent {
  type: 'progress' | 'executing' | 'executed' | 'execution_cached' | 'execution_error';
  promptId?: string;
  node?: string;
  value?: number;
  max?: number;
  nodes?: string[];
}
```

## 错误

ComfyUI推出的非-2xx响应 `ComfyUIRequestError` (单位:千美元) `ApiError` 从 `@happyvertical/utils`) (中文(简体) ). 它携带 `status`, (中文(简体) ), `method`, (中文(简体) ), `path` 编辑 回应 `body` (分出JSON,或作生文. ComfyUI 拒绝一个提示 失败验证, 如缺少模型文件, 包含 HTTP 400; 那么错误 暴露尸体的痕迹 `node_errors` 作为 `nodeErrors` 联 合 国 `error` 对象为 `promptError`。消息保留 `ComfyUI request failed: <status> <body>` 语句.

```typescript
import { ComfyUIRequestError } from '@happyvertical/comfyui';

try {
  await client.queuePrompt(workflow);
} catch (error) {
  if (error instanceof ComfyUIRequestError && error.nodeErrors) {
    console.error('Prompt rejected:', error.nodeErrors);
  }
  throw error;
}
```

## 使用大小写

### AI 视频生成管道

```typescript
import { ComfyUIClient, injectWorkflowParams } from '@happyvertical/comfyui';

async function generateVideo(seedImage: string, audioFile: string) {
  const client = new ComfyUIClient({ url: 'http://localhost:8188' });
  await client.connect();

  try {
    // Upload inputs
    await client.uploadImage(fs.readFileSync(seedImage), 'seed.png');
    await client.uploadImage(fs.readFileSync(audioFile), 'audio.wav');

    // Load lip-sync workflow
    const workflow = JSON.parse(fs.readFileSync('lipsync-workflow.json', 'utf-8'));
    const modified = injectWorkflowParams(workflow, {
      seedImage: '3',
      audioFile: '5',
    }, {
      seedImage: 'input/seed.png',
      audioFile: 'input/audio.wav',
    });

    // Execute with progress
    const result = await client.queuePrompt(modified);
    const history = await client.waitForCompletion(result.promptId, {
      onProgress: (e) => {
        if (e.type === 'progress') {
          console.log(`Rendering: ${Math.round((e.value! / e.max!) * 100)}%`);
        }
      },
    });

    // Download output
    const output = history.outputs['SaveVideo'];
    return await client.downloadOutput(output.videos[0].filename);
  } finally {
    await client.disconnect();
  }
}
```

### 批量图像生成

```typescript
async function generateBatch(prompts: string[]) {
  const client = new ComfyUIClient({ url: 'http://localhost:8188' });
  await client.connect();

  const results = [];
  for (const prompt of prompts) {
    const workflow = injectWorkflowParams(baseWorkflow, { prompt: '6' }, { prompt });
    const result = await client.queuePrompt(workflow);
    const history = await client.waitForCompletion(result.promptId);
    results.push(history);
  }

  await client.disconnect();
  return results;
}
```

## 所需资源

-   运行和可访问的 ComfyUI 服务器
-   节点.js 20+或 Bun
-   运行时的 WebSocket 支持

## 许可证

这个包是HE SDK的一部分,根据麻省理工学院的许可证获得许可——见 [自由主义](https://npmcn.com/package/LICENSE) 详细文件.

## 常见问题

### @happyvertical/comfyui 是什么？

ComfyUI API 客户端,用于工作流程管弦和视频生成

### 如何安装 @happyvertical/comfyui？

在项目目录运行 npm install @happyvertical/comfyui，或使用 pnpm add / yarn add / bun add。

### @happyvertical/comfyui 支持 TypeScript 吗？

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

### @happyvertical/comfyui 支持 ESM 还是 CommonJS？

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

### @happyvertical/comfyui 可以商用吗？

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

### @happyvertical/comfyui 的下载量有多少？

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

### @happyvertical/comfyui 还在维护吗？

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

