NoCoin深度指南：从架构到实践的完整路径

一、核心功能解析

1.1 项目概述

NoCoin是一款轻量级浏览器扩展（Browser Extension），旨在阻止未经用户许可的加密货币挖矿脚本（如Coinhive）利用设备资源。该项目通过拦截已知挖矿域名请求、提供用户控制界面和动态配置管理，实现对浏览器环境的主动防护。

1.2 核心功能模块

1.2.1 挖矿请求拦截系统

• 实时检测机制：通过webRequest API监控网络请求，匹配黑名单规则实现拦截
• 动态响应策略：根据域名白名单状态和全局开关动态调整拦截行为
• 视觉反馈系统：通过浏览器动作图标变化（如logo_enabled_blocked.png）直观展示拦截状态

1.2.2 用户控制中心

• 状态切换：提供全局启用/禁用开关（默认快捷键：Toggle按钮）
• 域名管理：支持临时/永久白名单配置（1分钟/30分钟/永久三个时效选项）
• 状态展示：实时显示当前页面挖矿活动检测结果和扩展运行状态

1.2.3 规则管理系统

• 黑名单机制：通过blacklist.txt维护已知挖矿域名列表
• 规则更新：支持远程黑名单自动拉取与本地 fallback 机制
• 配置持久化：使用localStorage保存用户偏好设置

二、关键文件作用

2.1 项目架构

NoCoin/
├── src/                  # 源代码目录
│   ├── img/              # 图标资源
│   ├── js/               # 核心脚本
│   │   ├── background.js # 后台服务脚本
│   │   └── popup.js      # 交互界面脚本
│   ├── styles/           # 样式文件
│   ├── view/             # 界面文件
│   │   └── popup.html    # 弹出界面
│   ├── blacklist.txt     # 挖矿域名黑名单
│   └── manifest.json     # 扩展清单文件
├── gulpfile.js           # 构建配置
└── package.json          # 项目依赖配置

模块依赖关系：

• manifest.json → 定义扩展基础配置，指定background.js为后台脚本
• background.js ←→ popup.js → 通过chrome.runtime.onMessage实现消息通信
• blacklist.txt → 被background.js加载用于构建拦截规则
• popup.html → 引用popup.css和popup.js构建用户界面

2.2 核心配置文件解析

2.2.1 清单文件（manifest.json）

参数	默认值	建议配置	说明
manifest_version	2	2	清单版本，v2支持传统扩展架构，v3引入Service Worker模式
permissions	["activeTab", "tabs", "<all_urls>", "webRequest", "webRequestBlocking"]	保持默认	必要权限集合，webRequest系列权限用于网络拦截
background.scripts	["js/background.js"]	保持默认	后台运行脚本，负责核心拦截逻辑
browser_action.default_popup	"view/popup.html"	保持默认	点击扩展图标时展示的界面文件
icons	{"128": "img/logo_enabled.png"}	补充多尺寸图标	建议添加16x16、48x48尺寸以适配不同场景

关键代码片段：

{
  "manifest_version": 2,
  "permissions": [
    "webRequest", 
    "webRequestBlocking", 
    "<all_urls>"  // 授予拦截所有URL请求的权限
  ],
  "background": {
    "scripts": ["js/background.js"],
    "persistent": true  // 保持后台脚本持续运行
  }
}

2.2.2 构建配置（gulpfile.js）

该文件定义了多平台构建流程，支持Chrome、Firefox、Edge等浏览器。核心任务包括：

1. 资源处理：

   • JavaScript转译（Babel）与压缩（Uglify）
   • CSS压缩（cleanCSS）
   • 清单文件版本注入

2. 打包策略：

   • Chrome：生成ZIP格式扩展包
   • Firefox：生成XPI格式扩展包
   • Chromium：生成CRX格式签名包

构建流程时序：

开始 → 清理旧文件 → 复制静态资源 → 处理JS/CSS → 生成清单文件 → 打包输出 → 结束

2.3 核心业务代码

2.3.1 后台拦截逻辑（background.js）

// 核心拦截器实现
chrome.webRequest.onBeforeRequest.addListener(details => {
  // 检查全局开关状态
  if (!config.toggle) return { cancel: false };
  
  // 检查域名白名单状态
  if (isDomainWhitelisted(domains[details.tabId])) {
    // 白名单域名：显示特殊图标并允许请求
    chrome.browserAction.setIcon({
      path: 'img/logo_enabled_whitelisted.png',
      tabId: details.tabId
    });
    return { cancel: false };
  }
  
  // 拦截挖矿请求并显示拦截状态
  chrome.browserAction.setIcon({
    path: 'img/logo_enabled_blocked.png',
    tabId: details.tabId
  });
  return { cancel: true };  // 关键：返回true表示拦截请求
}, { urls: blacklistedUrls }, ['blocking']);

2.3.2 黑名单规则（blacklist.txt）

采用URL模式匹配规则，支持通配符和协议指定：

*://coinhive.com/lib*          # 拦截Coinhive库加载
wss://*.coinhive.com/proxy*    # 拦截WebSocket连接
*://jsecoin.com/server*        # 拦截JSEcoin服务请求

三、快速上手指南

3.1 环境准备

3.1.1 开发环境

• Node.js（v8.0+）
• npm（v5.0+）
• Gulp CLI（全局安装）

3.1.2 项目获取

git clone https://gitcode.com/gh_mirrors/no/NoCoin
cd NoCoin
npm install

3.2 构建与安装

3.2.1 构建命令

# 构建所有平台版本
gulp default

# 仅构建Chrome版本
gulp chrome

3.2.2 浏览器安装

• Chrome/Chromium：

  1. 打开chrome://extensions
  2. 启用"开发者模式"
  3. 点击"加载已解压的扩展程序"
  4. 选择dist/tmp目录

• Firefox：

  1. 打开about:debugging
  2. 点击"临时载入附加组件"
  3. 选择dist/firefox目录下的XPI文件

3.3 基本操作

3.3.1 界面说明

• 状态指示：扩展图标显示当前状态（启用/禁用/拦截/白名单）
• Toggle按钮：切换全局拦截开关
• 白名单管理：选择时效后点击"White list"添加当前域名到白名单

3.3.2 高级配置

• 自定义黑名单：编辑src/blacklist.txt添加自定义拦截规则
• 配置持久化：用户设置自动保存在localStorage中，清除浏览器数据会重置

四、常见问题排查

4.1 扩展无法安装

症状：Chrome提示"程序包无效" 解决方案：

1. 检查manifest.json格式是否正确（可使用JSONLint验证）
2. 确认manifest_version与浏览器版本兼容（v2支持Chrome 4及以上，v3需要Chrome 88+）
3. 检查文件路径是否符合清单定义（如background.js是否存在于指定位置）

4.2 拦截功能失效

排查步骤：

1. 检查扩展是否启用（chrome://extensions）
2. 确认Toggle按钮状态是否为启用（蓝色表示启用）
3. 查看当前域名是否在白名单中（点击扩展图标查看状态）
4. 检查blacklist.txt是否成功加载（背景页控制台可查看网络请求）

4.3 构建失败

常见原因：

• 依赖问题：运行npm install更新依赖
• Node版本过低：升级Node.js至v8.0以上
• 证书缺失：构建CRX格式需要certs/key.pem，可通过openssl生成

五、技术选型解析

5.1 清单版本选择

项目采用manifest_version: 2而非最新的v3版本，主要考虑：

• 兼容性：v2支持更多浏览器版本（包括旧版Chrome和Edge）
• 功能完整性：v2的webRequestBlocking权限在v3中受限于Service Worker
• 开发复杂度：v3的Service Worker模式需要重构背景页逻辑

5.2 拦截技术对比

拦截方案	实现方式	优势	局限
webRequest API	网络请求拦截	响应速度快，资源消耗低	需要特定权限，部分浏览器支持有限
内容脚本注入	DOM操作阻止执行	兼容性好	可能被绕过，性能开销大
DNS拦截	系统级域名过滤	全面拦截	需要系统权限，配置复杂

NoCoin选择webRequest API方案，在安全性和性能间取得平衡，适合浏览器扩展场景。

5.3 构建工具选择

采用Gulp而非Webpack的原因：

• 配置简单：适合小型项目快速上手
• 插件生态：丰富的专用插件（如gulp-crx-pack）
• 任务定义清晰：通过管道式操作直观定义构建流程