import puppeteer, { Browser, ConnectOptions, ElementHandle, GoToOptions, Page } from 'puppeteer-core' import { Context, h, hyphenate, Schema, Service } from 'koishi' import { SVG, SVGOptions } from './svg' import find from 'puppeteer-finder' import Canvas from './canvas' import { pathToFileURL } from 'node:url' import { resolve } from 'node:path' import { } from '@cordisjs/plugin-proxy-agent' import { } from 'koishi-plugin-fonts' export * from './svg' declare module 'koishi' { interface Context { puppeteer: Puppeteer } } type RenderCallback = (page: Page, next: (handle?: ElementHandle) => Promise) => Promise class Puppeteer extends Service { static [Service.provide] = 'puppeteer' static inject = ['http'] browser: Browser executable: string private browserWSEndpoint: string constructor(ctx: Context, public config: Puppeteer.Config) { super(ctx, 'puppeteer') if (this.config.enableCanvas !== false) { ctx.plugin(Canvas) } // 注册 HTML 组件 // 只在构造时注册一次用于指令重启 this.registerHtmlComponent() // 根据配置决定是否注册重启指令 if (this.config.enableRestartCommand !== false) { ctx.command('puppeteer.restart', '重启 Puppeteer 浏览器服务') .action(async ({ session }) => { try { session?.send('正在重启 Puppeteer 服务...') // 停止当前浏览器实例 await this.stopBrowser() // 重新启动浏览器 await this.startBrowser() return '✅ Puppeteer 服务重启成功' } catch (error) { ctx.logger.error('Puppeteer 服务重启失败:', error) return `❌ Puppeteer 服务重启失败: ${error.message}` } }) } } private registerHtmlComponent() { const transformStyle = (source: {}, base = {}) => { return Object.entries({ ...base, ...source }).map(([key, value]) => { return `${hyphenate(key)}: ${Array.isArray(value) ? value.join(', ') : value}` }).join('; ') } this.ctx.component('html', async (attrs, children) => { const head: h[] = [] const transform = (element: h) => { if (element.type === 'head') { head.push(...element.children) return } const attrs = { ...element.attrs } if (typeof attrs.style === 'object') { attrs.style = transformStyle(attrs.style) } return h(element.type, attrs, element.children.map(transform).filter(Boolean)) } // 确保浏览器已连接 await this.ensureConnected() const page = await this.page() try { if (attrs.src) { await page.goto(attrs.src) } else { await page.goto(pathToFileURL(resolve(__dirname, '../index.html')).href) const bodyStyle = typeof attrs.style === 'object' ? transformStyle({ display: 'inline-block' }, attrs.style) : ['display: inline-block', attrs.style].filter(Boolean).join('; ') const content = children.map(transform).filter(Boolean).join('') const lang = attrs.lang ? ` lang="${attrs.lang}"` : '' await page.setContent(` ${head.join('')} ${content} `) } await page.waitForNetworkIdle({ timeout: attrs.timeout ? +attrs.timeout : undefined, }) const body = await page.$(attrs.selector || 'body') const clip = await body.boundingBox() const screenshot = await page.screenshot({ clip }) as Buffer return h.image(screenshot, 'image/png') } finally { await page?.close() } }) } async start() { await this.startBrowser() } private async startBrowser() { const { remote, endpoint, executablePath, headers, headless, args = [], ...config } = this.config try { if (remote) { if (!endpoint) { throw new Error('远程浏览器模式下必须提供 endpoint 参数') } const connectOptions: ConnectOptions = { headers, ...config } try { const endpointURL = new URL(endpoint) if (['ws:', 'wss:'].includes(endpointURL.protocol)) { // 不再检查路径格式，接受任何有效的 WebSocket URL connectOptions.browserWSEndpoint = endpoint } else if (['http:', 'https:'].includes(endpointURL.protocol)) { connectOptions.browserURL = endpoint } else { throw new Error(`不支持的协议: ${endpointURL.protocol}，endpoint 必须以 ws://, wss://, http:// 或 https:// 开头`) } } catch (e) { if (e instanceof TypeError) { throw new Error(`无效的 endpoint URL: ${endpoint}，请检查格式是否正确`) } throw e } try { this.ctx.logger.info('正在连接远程浏览器: %c', endpoint) this.browser = await puppeteer.connect(connectOptions) this.ctx.logger.info('远程浏览器连接成功。') // 保存 WebSocket 端点，无论是直接提供的还是从 HTTP URL 获取的 if (connectOptions.browserWSEndpoint) { this.browserWSEndpoint = connectOptions.browserWSEndpoint } else if (this.browser.wsEndpoint) { // 如果使用 HTTP URL，从浏览器实例获取 WebSocket 端点 this.browserWSEndpoint = this.browser.wsEndpoint() this.ctx.logger.debug('从 HTTP URL 获取 WebSocket 端点: %c', this.browserWSEndpoint) } } catch (e) { // 处理连接错误 if (e.message?.includes('ECONNREFUSED')) { throw new Error(`无法连接到远程浏览器 ${endpoint}，请确保远程浏览器已启动并且端口可访问`) } else if (e.message?.includes('not opened')) { throw new Error(`远程浏览器连接被拒绝，请确保提供的 endpoint 是正确的并且浏览器已启动调试模式`) } else { // 确保包含原始错误信息 throw new Error(`连接远程浏览器失败: ${e.message || e}`) } } } else { // 查找可执行文件路径 this.executable = executablePath || find() if (!this.executable) { throw new Error('未找到 Chrome 可执行文件，请手动指定 executablePath 参数') } if (!executablePath) { this.ctx.logger.info('找到 Chrome 可执行文件: %c', this.executable) } // 处理代理设置 const localArgs = [...args] const { proxyAgent } = this.ctx.http.config if (proxyAgent && !localArgs.some(arg => arg.startsWith('--proxy-server'))) { localArgs.push(`--proxy-server=${proxyAgent}`) } try { // 启动浏览器 this.ctx.logger.info('正在启动本地浏览器...') this.browser = await puppeteer.launch({ executablePath: this.executable, headless, args: localArgs, ...config }) this.ctx.logger.info('本地浏览器启动成功。') this.browserWSEndpoint = this.browser.wsEndpoint() } catch (e) { if (e.message?.includes('Failed to launch')) { throw new Error(`启动浏览器失败，请检查 Chrome 是否已安装或路径是否正确: ${e.message}`) } else { throw new Error(`启动浏览器失败: ${e.message || e}`) } } } } catch (error) { this.ctx.logger.error(`Puppeteer 初始化失败: `, error) throw error } } async stop() { await this.stopBrowser() } private async stopBrowser() { try { if (this.browser) { if (this.config.remote) { await this.browser.disconnect() } else { await this.browser.close() } this.browser = null this.browserWSEndpoint = null } } catch (error) { this.ctx.logger.warn('停止浏览器时出现错误:', error.message) } } // 检查浏览器连接状态并尝试重连 private async ensureConnected() { // 如果浏览器已连接，直接返回 if (this.browser.connected) return // 如果未启用重连，则抛出异常 if (this.config.enableReconnect === false) { throw new Error('浏览器连接已断开，且未启用自动重连') } // 检查是否有可用的重连端点 const hasReconnectEndpoint = this.browserWSEndpoint || this.config.endpoint if (!hasReconnectEndpoint) { throw new Error('浏览器连接已断开，且没有可用的重连端点') } // 尝试重连，使用配置的最大重试次数 let retryCount = 0 const maxRetries = this.config.maxReconnectRetries ?? 3 while (retryCount < maxRetries) { try { this.ctx.logger.info(`浏览器连接已断开，尝试重新连接... (尝试 ${retryCount + 1}/${maxRetries})`) // 如果设置了重连间隔，则等待指定时间 if (this.config.reconnectInterval > 0) { await new Promise(resolve => setTimeout(resolve, this.config.reconnectInterval)) } // 准备连接选项 const connectOptions: ConnectOptions = { ...this.config } // 优先使用保存的 WebSocket 端点，如果没有则使用配置的端点 if (this.browserWSEndpoint) { connectOptions.browserWSEndpoint = this.browserWSEndpoint this.ctx.logger.debug('使用保存的 WebSocket 端点重连: %c', this.browserWSEndpoint) } else if (this.config.endpoint) { // 检查端点类型 try { const endpointURL = new URL(this.config.endpoint) if (['ws:', 'wss:'].includes(endpointURL.protocol)) { connectOptions.browserWSEndpoint = this.config.endpoint this.ctx.logger.debug('使用配置的 WebSocket 端点重连: %c', this.config.endpoint) } else if (['http:', 'https:'].includes(endpointURL.protocol)) { connectOptions.browserURL = this.config.endpoint this.ctx.logger.debug('使用配置的 HTTP 端点重连: %c', this.config.endpoint) } } catch (e) { this.ctx.logger.warn('解析端点 URL 失败: %c', e.message) } } // 尝试重新连接 this.browser = await puppeteer.connect(connectOptions) // 检查连接是否成功 if (this.browser.connected) { this.ctx.logger.info('浏览器重新连接成功') // 保存新的 WebSocket 端点 if (this.browser.wsEndpoint) { this.browserWSEndpoint = this.browser.wsEndpoint() this.ctx.logger.debug('保存新的 WebSocket 端点: %c', this.browserWSEndpoint) } return } else { throw new Error('连接后浏览器状态仍为断开') } } catch (e) { retryCount++ // 检查是否是 404 错误，如果是，则尝试使用原始配置重新连接 if (e.message?.includes('404') || e.message?.includes('Unexpected server response: 404')) { this.ctx.logger.warn('检测到 404 错误，尝试使用原始配置重新连接') try { // 重置端点信息 this.browserWSEndpoint = null // 使用原始配置重新连接 const originalOptions: ConnectOptions = { ...this.config } if (this.config.endpoint) { const endpointURL = new URL(this.config.endpoint) if (['ws:', 'wss:'].includes(endpointURL.protocol)) { originalOptions.browserWSEndpoint = this.config.endpoint } else if (['http:', 'https:'].includes(endpointURL.protocol)) { originalOptions.browserURL = this.config.endpoint } } this.browser = await puppeteer.connect(originalOptions) // 检查连接是否成功 if (this.browser.connected) { this.ctx.logger.info('使用原始配置重新连接成功') // 保存新的 WebSocket 端点 if (this.browser.wsEndpoint) { this.browserWSEndpoint = this.browser.wsEndpoint() this.ctx.logger.debug('保存新的 WebSocket 端点: %c', this.browserWSEndpoint) } return } } catch (reconnectError) { this.ctx.logger.warn('使用原始配置重新连接失败:', reconnectError.message) } } if (retryCount >= maxRetries) { this.ctx.logger.error(`浏览器重新连接失败 (${retryCount}/${maxRetries}):`, e.message) throw new Error(`浏览器重新连接失败: ${e.message}`) } else { this.ctx.logger.warn(`浏览器重新连接失败，将重试 (${retryCount}/${maxRetries}):`, e.message) // 增加重试间隔 await new Promise(resolve => setTimeout(resolve, this.config.reconnectInterval * retryCount)) } } } } page = async (options?: Puppeteer.PageOptions) => { let page try { // 确保浏览器已连接 await this.ensureConnected() // 创建新页面 page = await this.browser.newPage() if (options) { if (options?.beforeGotoPage) { await options.beforeGotoPage(page) } await page.goto(`${pathToFileURL(options.url)}`, options?.gotoOptions) if (options?.content) { await page.setContent(options.content) } if (options?.families?.length && this.ctx.fonts) { try { const fonts = await this.ctx.fonts.get(options.families) await Promise.all(fonts.map(async (font) => { if (font.format === 'google') { await page.addStyleTag({ content: `@import url('${font.path}')` }) } else { await page.evaluate((font) => { const fontFace = new FontFace( font.family, `url(${font.path}) format('${font.format}')`, font.descriptors, ) document.fonts.add(fontFace) }, font) } })) } catch (e) { this.ctx.logger.warn('加载字体失败，将使用系统默认字体：', e.message) } } } } catch (err) { if (page) { await page.close() } this.ctx.logger.error('failed to create page: %s', err) throw err } return page } svg = async (options?: SVGOptions) => { // 确保浏览器已连接 await this.ensureConnected() return new SVG(options) } render = async (content: string, callback?: RenderCallback, families?: string[]) => { // 确保浏览器已连接 await this.ensureConnected() const url = resolve(__dirname, '../index.html') const page = await this.page({ url, content, families }) const renderConfig = this.config.render || {} if (families?.length) { try { await page.addStyleTag({ content: `* {font-family: ${families.map((f) => `'${f}'`).join(', ')};}` }) await page.evaluate(async () => { await document.fonts.ready await new Promise(resolve => setTimeout(resolve, 100)) }) } catch (e) { this.ctx.logger.warn('应用字体样式失败：', e.message) } } callback ||= async (_, next) => page.$('body').then(next) const output = await callback(page, async (handle) => { const clip = handle ? await handle.boundingBox() : null const screenshotOptions = { clip, ...renderConfig } const buffer = await page.screenshot(screenshotOptions) as Buffer const imageType = renderConfig.type || 'png' return h.image(buffer, `image/${imageType}`).toString() }) page.close() return output } } namespace Puppeteer { export interface PageOptions { beforeGotoPage?: (page: Page) => Promise url: string gotoOptions?: GoToOptions content?: string families?: string[] } export const filter = false; export const usage = ` --- 本插件提供浏览器 API 服务，主要用于网页截图、生成图片等功能。 **重要提示：** 1. **浏览器环境要求：** 为确保插件正常运行，请确保您的系统已安装 Chromium 浏览器，或已配置远程浏览器服务。 2. **版本匹配：** 建议保持 Chromium/Chrome 浏览器与本插件同步更新，以避免因版本不匹配导致的功能异常。 3. **Windows 系统兼容性：** 如果您在 Windows 服务器上运行，为支持最新版 Puppeteer 及其捆绑的 Chromium，您的操作系统至少需要是 **Windows Server 2016 或更高版本**。注意： Windows Server 2012 R2 及更早版本已无法满足最新 Chrome 的运行要求。 --- **服务依赖：** - **必需服务：** http（自带服务，无需额外安装） - **可选服务：** [fonts](/market?keyword=font+email:shigma10826@gmail.com+email:saarchaffee@qq.com) ---

➣ 点我前往项目地址

--- `; type LaunchOptions = Parameters[0] & {} export type ImageType = 'png' | 'jpeg' | 'webp' export interface Config extends LaunchOptions, ConnectOptions { enablePuppeteer?: boolean enableCanvas?: boolean enableRestartCommand?: boolean remote?: boolean endpoint?: string headers?: Record enableReconnect?: boolean reconnectInterval?: number maxReconnectRetries?: number render?: { type?: ImageType quality?: number } } export const Config = Schema.intersect([ Schema.object({ remote: Schema.boolean().description('是否连接到远程浏览器。').default(false), }).description('连接设置'), Schema.union([ Schema.object({ remote: Schema.const(true).required(), endpoint: Schema.string().description( '远程浏览器的端点。
' + '例：
' + 'WebSocket URL: `ws://localhost:14550/devtools/browser/[id]`
' + 'HTTP URL: `http://localhost:14550`
' ).required(), headers: Schema.dict(String).role('table').description( '连接到远程浏览器时使用的 HTTP 请求头。
' + '注意：这与本地模式的 `args` 不同，headers 只影响连接请求，不影响浏览器本身的行为。
' + '常用于设置身份验证、API密钥或自定义标识等。详细示例请参考 README。' ), }), Schema.object({ remote: Schema.const(false).default(false), executablePath: Schema.string().description( 'Chrome/Chromium 可执行文件的路径。
' + '如果不指定，将自动从系统中查找。
' + '如果自动查找失败，请手动指定此路径。' ), headless: Schema.boolean().description('是否开启[无头模式](https://developer.chrome.com/blog/headless-chrome/)。无头模式下浏览器不会显示界面。').default(true), args: Schema.array(String) .description( '启动 Chrome/Chromium 浏览器时传递的命令行参数。
' + '常用参数：
' + '`--no-sandbox`: 禁用沙箱（在 Docker 或 root 用户下常用）
' + '`--disable-gpu`: 禁用 GPU 加速
' + '更多 [Chromium 参数请参考这个页面](https://peter.sh/experiments/chromium-command-line-switches/)。' ) .default(process.getuid?.() === 0 ? ["--no-sandbox", "--disable-gpu"] : []), }), ]), Schema.object({ enablePuppeteer: Schema.boolean().description('是否注册 puppeteer 服务。').default(true), enableCanvas: Schema.boolean().description('是否注册 canvas 服务。（默认关闭。）
注意: 这与[`koishi-plugin-canvas`](/market?keyword=koishi-plugin-canvas+email:shigma10826@gmail.com+email:void@anillc.cn+email:i.dlist@outlook.com)的`canvas`服务同名但API不一致。').default(false), enableRestartCommand: Schema.boolean().description('是否注册 puppeteer.restart 重启指令。启用后可通过指令重启浏览器服务。').default(false), enableReconnect: Schema.boolean().description('是否启用浏览器自动重连功能。当浏览器连接断开时，会尝试重新连接。').default(true), reconnectInterval: Schema.number().description('浏览器重连尝试的间隔时间（毫秒）。').default(1000), maxReconnectRetries: Schema.number().description('浏览器重连最大尝试次数。').default(3), }).description('功能设置'), Schema.object({ render: Schema.intersect([ Schema.object({ type: Schema.union(['png', 'jpeg', 'webp'] as const).description('默认渲染的图片类型。').default('png'), }), Schema.union([ Schema.object({ type: Schema.const('png'), }), Schema.object({ quality: Schema.number().min(0).max(100).step(1).description('默认渲染的图片质量。').default(80), }), ]), ]), }).description('渲染设置'), Schema.object({ defaultViewport: Schema.object({ width: Schema.natural().description('默认的视图宽度。').default(1280), height: Schema.natural().description('默认的视图高度。').default(768), deviceScaleFactor: Schema.number().min(0).description('默认的设备缩放比率。').default(2), }), ignoreHTTPSErrors: Schema.boolean().description('在导航时忽略 HTTPS 错误。').default(false), }).description('浏览器设置'), ]) as Schema } export default Puppeteer