youtube的fork,📊 自动检测聊天中的 YouTube 链接，通过 YouTube Data API v3 获取视频信息 ，支持文本发送 或 Puppeteer 渲染的预览信息图片 。支持独立模式/REST 分布式部署、SOCKS/HTTP 代理、平台白名单。

插件发布
1

koishi-plugin-youtube-vincentzyu-fork

:dart: koishi-plugin-youtube-vincentzyu-fork

npm
npm-download

YouTube
Koishi

GitHub
Gitee

Koishi Forum
QQ群

💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入QQ群：259248174 🎉（这个群G了

💬 插件使用问题 / 🐛 Bug反馈 / 👨‍💻 插件开发交流，欢迎加入QQ群：1085190201 🎉

💡 在群里直接艾特我，回复的更快哦~ ✨

:tv: 自动识别聊天中的 YouTube 链接，通过 YouTube Data API v3 获取视频信息，并返回文本或 Puppeteer 渲染图片。

:fork_and_knife: forked from H4M5TER/koishi-plugin-youtube

:sparkles: 功能特性

  • :mag_right: 自动检测聊天里的 YouTube 视频链接。

  • :bar_chart: 通过 YouTube Data API v3 获取标题、频道、发布时间、播放量、简介、标签和封面图。

  • :speech_balloon: 支持文本消息输出。

  • :framed_picture: 支持 Puppeteer 渲染成 YouTube 风格预览图。

  • :globe_with_meridians: 支持 axios 或 Koishi ctx.http 两种请求方式。

  • :socks: 支持 HTTP / HTTPS / SOCKS4 / SOCKS5 / SOCKS5H 代理。

  • :shield: 支持按平台配置用户白名单，避免在不合适的群聊环境自动解析。

  • :desktop_computer: 支持 REST 服务模式，可拆成“解析客户端”和“渲染服务端”部署。

  • :abc: 支持自定义 Puppeteer 渲染字体，默认下载到 Koishi 数据目录。

  • :receipt: 支持会话侧和控制台侧详细调试输出。

:framed_picture: 预览

text_and_image

only_image

:package: 依赖服务

服务 是否必须 用途
http 可选 当 requestLib = ctx_http 时用于请求 YouTube API 和缩略图
puppeteer 可选 当启用图片输出或 REST 渲染服务时用于截图

:warning: 如果只发送文本，并且使用 axios 请求库，可以不启用 Puppeteer。

:framed_picture: 如果选择 image 输出，请启用 Puppeteer 插件。

:rocket: 使用方法

1. 获取 YouTube API Key :key:

  1. 打开 YouTube Data API v3 文档。

  2. 在 Google Cloud 创建项目。

  3. 启用 YouTube Data API v3。

  4. 创建 API Key。

  5. 将 API Key 填入 Koishi 插件配置里的 youtubeApiKey。

2. 启用插件 :gear:

在 Koishi 控制台启用本插件，并至少配置：

  • youtubeApiKey

  • requestLib

  • 代理配置，如果你的运行环境不能直连 YouTube / Google API

  • msgFormArr，选择发送纯文本、图片、text-with-image 图文或合并转发

3. 发送链接测试 :tv:

插件会自动识别以下常见链接：


https://youtu.be/{video_id}

https://www.youtube.com/watch?v={video_id}

https://www.youtube.com/shorts/{video_id}

https://www.youtube.com/embed/{video_id}

:gear: 工作模式

:house: standalone 独立模式

默认模式。当前 Koishi 实例直接完成：


识别链接 -> 请求 YouTube API -> 下载封面 -> 发送文本 / Puppeteer 出图

适合普通使用场景。

:electric_plug: rest_client 客户端模式

当前 Koishi 实例只负责监听聊天消息，然后请求另一台 REST 服务实例：


实例 A：监听聊天消息 -> 请求实例 B

实例 B：解析 YouTube / Puppeteer 渲染 -> 返回结果

适合把 Puppeteer 渲染放到另一台机器上，或者多实例共用一个渲染服务。

:desktop_computer: RESTful 服务端模式

打开 enableRestfulService 后，本插件会启动 Fastify 服务，提供：

接口 方法 说明
/parse POST 传入 { "url": "..." }，返回视频解析结果
/render POST 传入已解析 payload，返回渲染图片 Base64
/render-from-url POST 传入 { "url": "..." }，直接解析并渲染图片

:wrench: REST 服务依赖 Puppeteer。插件内部会等 Puppeteer 服务可用后再启动 REST 服务。

:jigsaw: 配置项说明

:wrench: 基础配置

配置项 类型 默认值 说明
youtubeApiKey string 必填 YouTube Data API v3 的 API Key
enableParseUrlFromPlatformSession boolean true 是否从聊天消息里自动解析 YouTube URL
middlewareWorkMode standalone / rest_client standalone 工作模式
restClientTargetUrl string http://127.0.0.1:8020 REST 客户端模式下的目标服务地址

:globe_with_meridians: 网络请求与代理

配置项 类型 默认值 说明
requestLib ctx_http / axios axios 网络请求库
proxyProtocol http / https / socks4 / socks5 / socks5h socks5h 代理协议
proxyIp string 127.0.0.1 代理地址
proxyPort number 7891 代理端口
userAgent string Chrome UA 请求 YouTube API 和缩略图时使用的 User-Agent

:socks: 如果你用 Clash / Mihomo，常见 SOCKS 端口可能是 7891 或你自己配置的端口。

:satellite: 如果选择 ctx_http，代理通常由 Koishi HTTP 插件统一管理。

:memo: 视频简介配置

配置项 类型 默认值 说明
hideDescription boolean false 是否隐藏视频简介
maxDescriptionLength number 300 简介最大长度，超出会截断

:speech_balloon: 消息发送配置

配置项 类型 默认值 说明
msgFormArr array ["text-with-image", "image", "forward"] 发送形式，支持 text、image、text-with-image、forward
quoteWhenSend boolean true 回复时是否引用原消息

发送形式说明：

  • text：只发送标题、频道、发布时间、播放量、简介和标签。

  • image：只发送 Puppeteer 渲染的视频预览卡片。

  • text-with-image：发送缩略图 + 文本详情，等价于旧版 text 行为。

  • forward：发送 OneBot 合并转发消息。

:abc: Puppeteer 图片字体配置

配置项 类型 默认值 说明
enableCustomFont boolean true 是否启用自定义渲染字体
autoDownloadFont boolean true 字体不存在时是否自动下载
customFontPath string ctx.baseDir/data/fonts/LXGWWenKaiMono-Regular.ttf 自定义字体绝对路径，默认使用 Koishi 数据目录下的字体文件
fontDownloadUrl string LXGW WenKai 下载地址 自动下载字体的 URL

默认字体路径遵循 Koishi 数据目录规范：


ctx.baseDir/data/fonts/LXGWWenKaiMono-Regular.ttf

路径规则：

  • :file_folder: customFontPath 默认值：使用上面的默认路径，并允许自动下载。

  • :file_folder: customFontPath 留空：不使用自定义字体，直接回退系统字体。

  • :file_folder: customFontPath 填绝对路径且文件存在：直接使用该字体。

  • :file_folder: customFontPath 填相对路径：不支持，直接回退系统字体。

  • :file_folder: customFontPath 填绝对路径但文件不存在：直接回退系统字体。

  • :inbox_tray: 只有配置值等于默认路径、文件缺失且 autoDownloadFont = true 时，才会从 fontDownloadUrl 下载。

  • :abc: 支持常见字体格式：.ttf、.otf、.woff、.woff2。

:shield: 平台白名单配置

配置项 类型 默认值 说明
platformWhitelistArr array onebot / 1830540513 平台 + 用户 ID 白名单
sendWhiteListHint boolean false 是否发送白名单命中 / 跳过提示

白名单配置示例：

[
{
"platformName": "onebot",
"userIdWhilelist": ["123456789", "987654321"]
}
]

:desktop_computer: REST 服务配置

配置项 类型 默认值 说明
enableRestfulService boolean false 是否启动 RESTful 服务
restServiceBindIp string 0.0.0.0 REST 服务监听 IP
restServiceBindPort number 18020 REST 服务监听端口

:mag_right: 调试配置

配置项 类型 默认值 说明
enableVerboseSessionOutput boolean false 错误时向聊天平台发送更详细的调试信息
enableVerboseConsoleOutput boolean false 在 Koishi 控制台输出更详细的 API / 网络错误

:test_tube: 常见配置组合

只发文字 :page_facing_up:

  • msgFormArr = ["text"]

  • requestLib = axios

  • 不需要 Puppeteer

发图片 :framed_picture:

  • msgFormArr = ["image"] 或 ["text-with-image", "image"]

  • 启用 Puppeteer 插件

  • 确保 Koishi 运行环境可以启动浏览器

  • 默认会自动下载字体到 ctx.baseDir/data/fonts

默认组合 :package:

  • msgFormArr = ["text-with-image", "image", "forward"]

  • 同时发送图文、渲染图和合并转发

  • image 需要启用 Puppeteer 插件

  • forward 主要面向 OneBot 适配器

走 Koishi HTTP :satellite:

  • requestLib = ctx_http

  • 启用 Koishi http 服务

  • 代理交给 Koishi HTTP 插件配置

REST 分布式部署 :desktop_computer:

实例 B，渲染服务端：

  • enableRestfulService = true

  • restServiceBindIp = 0.0.0.0

  • restServiceBindPort = 18020

  • 启用 Puppeteer

实例 A，聊天客户端：

  • middlewareWorkMode = rest_client

  • restClientTargetUrl = http://实例B地址:18020

:fire_extinguisher: 排错建议

  • :x: API请求参数错误 (400)：检查 API Key 是否填写正确。

  • :x: API访问被拒绝 (403)：检查 API Key 权限、YouTube Data API v3 是否启用、配额是否用完。

  • :x: 视频不存在或已被删除 (404)：链接可能失效，或视频不可访问。

  • :x: 网络连接失败：检查代理协议、代理地址、端口和运行环境网络。

  • :x: 图片模式无响应：确认 Puppeteer 插件已启用，浏览器能正常启动。

  • :mag_right: 控制台会输出 msgFormArr 原始值、标准化结果、每个发送模式的命中/跳过/开始/完成/失败日志，方便定位某个模式没发的问题。

  • :mag_right: 打开 enableVerboseConsoleOutput 可以在控制台看到更详细的请求错误。

  • :speech_balloon: 打开 enableVerboseSessionOutput 可以把详细错误发到聊天里，调试完建议关闭。

:pushpin: 注意事项

  • YouTube Data API v3 有调用配额，频繁解析可能消耗较快。

  • 某些视频可能没有 maxres 缩略图，插件会 fallback 到 high 缩略图。

  • 国内网络环境通常需要代理才能访问 YouTube / Google API。

  • 白名单默认示例只是占位，请根据自己的平台和用户 ID 修改。

  • 图片渲染依赖Puppeteer，需要配置前置Puppeteer服务依赖

1 个赞
2
1 个赞
3

todo: onebot平台合并转发

图片
图片964×273 29.4 KB

1 个赞
4

https://www.npmjs.com/package/koishi-plugin-youtube-vincentzyu-fork

1 个赞
5

截止上文，目前npm的包版本:

{
  "name": "koishi-plugin-youtube-vincentzyu-fork",
  "version": "2.0.0-vincentzyufork.alpha.3+20251007",
  ...
1 个赞
6

更新一下readme喵，

图片
图片843×634 46.3 KB

2.1.1版本新增onebot合并转发支持，新增自定义字体支持喵

1 个赞
7

a1392abfed0e298ebff2fd4aba26201f
a1392abfed0e298ebff2fd4aba26201f1316×1101 226 KB

1 个赞
8

3b59538b4544696fa85bb363b9209a1a
3b59538b4544696fa85bb363b9209a1a534×826 132 KB

37fd61c66fb95aed4605b530d36a5715
37fd61c66fb95aed4605b530d36a5715534×872 109 KB

好看喵

1 个赞
9

3d8529a2a8422a34aeaf889b9879b6cb_720
3d8529a2a8422a34aeaf889b9879b6cb_720555×980 66.3 KB

磨砂玻璃是透一点好看还是不透好看喵

1 个赞