koishi-plugin-speedtest

云术工作室开发的一款对itdog测试结果截图的网站测速插件，内置强大的广告拦截功能。

功能特性

• 🚀 多种网络测试：支持 PING、TCP、HTTP、DNS 四种测试类型
• 📸 自动全屏截图：始终使用全屏截图，确保看到完整测速结果
• 🛡️ 内置广告拦截：无需浏览器扩展，彻底移除广告内容和容器
• ⚡ 智能等待机制：自动等待测速结果完全加载（可配置等待时间）
• 🎯 精准广告移除：CSS + JavaScript 双重拦截，不留广告空框
• 🔧 高度可配置：支持自定义广告选择器、拦截域名、等待时间等
• 🖥️ 独立运行：不依赖外部puppeteer服务，自主管理浏览器实例

安装要求

1. 系统需要安装 Chrome/Chromium 浏览器
2. Node.js 16+ 环境
3. Koishi 4.18.7+

安装方法

# 在 Koishi 插件市场搜索 speedtest 并安装
# 或手动安装
npm install koishi-plugin-speedtest

配置说明

在 koishi.yml 中添加以下配置：

plugins:
  speedtest:
    # 基本配置
    adblockEnabled: true          # 是否启用广告拦截（默认：true）
    timeout: 30000                # 页面加载超时时间（毫秒，默认：30000）
    viewportWidth: 1280           # 浏览器视口宽度（默认：1280）
    viewportHeight: 800           # 浏览器视口高度（默认：800）
    waitExtraTime: 8000           # 额外等待时间，确保测速结果完全加载（毫秒，默认：8000）
    
    # 广告拦截配置
    customAdSelectors:            # 自定义广告选择器（CSS选择器）
      - .right-ad
      - .ad-right
      - .ad-sidebar
      - .ad-header
      - .ad-footer
      - .sponsored-content
      - .promoted-list
      - .ad-container
      - .ad-wrapper
      - '[class*="ad-"]'
      - '[id*="ad-"]'
    
    blockAdDomains:               # 要拦截的广告域名
      - doubleclick.net
      - googleads.com
      - googlesyndication.com
      - adsystem.com
      - adnxs.com
      - adsrvr.org
      - ads.google.com
      - pagead2.googlesyndication.com
    
    blockGifImages: true          # 是否拦截所有GIF图片（很多广告使用GIF格式）
    blockImageExtensions:         # 要拦截的图片扩展名
      - .gif
      - .gif?
      - .swf
      - .webp?ad

使用方法

基本命令

所有命令都自动使用全屏截图，无需额外选项。

speedtest <目标地址> [选项]

命令选项

| 选项 | 缩写 | 说明 | 默认值 | |------|------|------|--------| | --type | -t | 测试类型：ping, tcp, http, dns | ping | | --dns | -d | DNS服务器地址（仅ping测试有效） | 223.5.5.5 |

快捷命令

• ping <目标地址> - PING测试（自动全屏截图）
• tcping <目标地址> - TCP端口测试（自动全屏截图）
• httping <目标地址> - HTTP测试（自动全屏截图）

使用示例

# PING测试（默认）
speedtest example.com
speedtest -t ping example.com

# 指定DNS服务器的PING测试
speedtest example.com -d 8.8.8.8
ping example.com -d 8.8.8.8

# TCP端口测试
speedtest example.com -t tcp
tcping example.com

# HTTP测试
speedtest example.com -t http
httping example.com

# DNS测试
speedtest example.com -t dns

广告拦截功能

三层拦截机制

1. CSS注入层：页面加载前注入广告隐藏样式，彻底移除广告容器
2. 请求拦截层：阻止广告资源加载（图片、脚本、iframe等）
3. JavaScript移除层：实时监控和移除动态加载的广告元素

广告拦截特点

• ✅ 彻底移除：不仅隐藏广告内容，还移除广告容器，不留空框
• ✅ GIF专门拦截：针对常见的GIF格式广告进行专门拦截
• ✅ 动态监控：使用MutationObserver实时监控新出现的广告
• ✅ 布局修复：自动调整页面布局，填充广告移除后的空间
• ✅ 性能优化：轻量级实现，不影响页面加载速度

注意事项

1. 浏览器要求

• 需要系统安装 Chrome/Chromium 浏览器
• 插件会自动查找浏览器可执行路径
• 如果找不到浏览器，请确保 Chrome/Chromium 已正确安装

2. 截图大小

• 全屏截图可能较大（1-3MB）
• 插件会自动检测并警告过大的截图
• 可通过调整viewportHeight和viewportWidth控制截图大小

3. 广告拦截不生效

如果发现广告未被正确拦截：

1. 检查配置中adblockEnabled是否为true
2. 查看日志中的广告拦截统计信息
3. 将未拦截的广告选择器添加到customAdSelectors配置
4. 将未拦截的广告域名添加到blockAdDomains配置

4. 测速结果不完整

如果截图看不到完整的测速结果：

1. 增加waitExtraTime配置值（默认8000ms）
2. 检查网络连接是否稳定
3. 查看日志中的页面加载和等待信息

故障排除

1. 提示"浏览器启动失败"

• 检查系统是否安装 Chrome/Chromium
• 确保浏览器可执行文件路径正确
• 查看日志中的浏览器启动错误信息

2. 截图失败或超时

• 增加timeout配置值
• 检查目标网站是否可访问
• 查看网络连接是否正常

3. 图片过大无法发送

• 降低viewportHeight和viewportWidth值
• 截图会自动优化，但过大图片可能仍需手动处理
• 考虑使用图片压缩工具处理截图

4. 广告拦截不彻底

• 查看日志中的广告拦截统计
• 添加未拦截的广告选择器到配置
• 确保blockGifImages为true以拦截GIF广告

开发说明

项目结构

speedtest/
├── src/
│   └── index.ts          # 主插件实现
├── lib/                  # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
└── readme.md            # 本文档

构建项目

cd koishi-plugin-speedtest
npm run build

依赖关系

• puppeteer-core: 浏览器自动化核心
• puppeteer-finder: 自动查找浏览器可执行路径
• koishi: Koishi框架依赖

更新日志

v0.2.0 (2026-02-23)

• 🎉 重大更新：移除浏览器扩展依赖，内置广告拦截
• 📸 全屏截图：所有命令自动使用全屏截图
• ⏱️ 智能等待：增加可配置的额外等待时间
• 🛡️ 广告拦截增强：彻底移除广告容器，不留空框
• 🐛 问题修复：修复GIF广告拦截，优化选择器

v0.1.0 (2026-02-23)

• 初始版本发布
• 支持PING、TCP、HTTP、DNS测试
• 基础广告拦截功能
• 支持浏览器扩展加载

许可证

MIT License

支持与反馈

如有问题或建议，请通过以下方式联系：

• Email: [email protected]
• QQ群: 955122914

感谢使用 koishi-plugin-speedtest！