怎么编写Javascript Bookmarklet在浏览器书签栏一键注入JS

编写一个 Javascript Bookmarklet（小书签）的核心做法，是将写好的 JavaScript 代码包裹在自执行函数表达式（IIFE）中，通过单行化和 URL 编码处理后，加上 javascript: 伪协议前缀，保存为浏览器的普通书签。在任何网页中点击该书签，浏览器就会以当前标签页为上下文同步执行这段代码，实现一键提取数据、修改页面样式或注入自动化辅助脚本。

一、Bookmarklet 的工作原理与上下文模型

普通浏览器书签记录的是一个 HTTP 或 HTTPS 协议的目标网址，当用户点击时，浏览器会在标签页中发起网络跳转并加载新页面。而 Bookmarklet 利用了浏览器原生支持的 javascript: 伪协议。当网址栏或书签地址以 javascript: 开头时，浏览器不会触发页面刷新，而是直接将冒号后面的字符串当作 JavaScript 脚本，派发给当前处于激活状态的标签页去执行。

这意味着注入的代码与宿主网页共享完全相同的运行时空间：它能够读取宿主页面的 document 节点树、访问当前域名下的 cookie 与 localStorage，并能借由当前页面的登录态调用后端的异步接口。对于临时的调试、页面样式微调或自动化操作而言，Bookmarklet 具有随点随用、跨设备同步简单且免去了繁琐的浏览器扩展（Extension）打包与审核流程的显著优势。

二、编写与安装 Bookmarklet 的四步标准流程

将一个实用的功能转化为可在书签栏一键运行的 Bookmarklet，需要按照以下四个标准步骤进行构建和校验。

第 1 步：使用 IIFE 闭包包裹逻辑代码

在编写原生 JavaScript 脚本时，绝不能将变量随意暴露在顶层作用域。因为当前网页可能已经运行了庞大的前端应用或第三方库，如果你的脚本直接声明了 var a = 1、let config = {} 或 function test(){}，极易覆盖宿主网页的已有变量，引发不可预料的报错。

标准规范是使用立即执行函数表达式（Immediately Invoked Function Expression, IIFE）将所有逻辑封闭在私有作用域中：

javascript:(function() {
  'use strict';
  // 在此处编写具体业务逻辑
  const pageTitle = document.title;
  console.log('当前页面标题为：', pageTitle);
})();

第 2 步：返回值处理与 URL 编码

浏览器在解析 javascript: 协议时存在一个关键规则：如果脚本执行完后产生了一个非 undefined 的返回值，浏览器会清空当前网页，并将该返回值转换为纯字符串渲染到整个视口中。为了杜绝这种情况，除了使用 IIFE 确保没有多余的 return 之外，还可以在语句前或末尾附加 void 0; 来强制抑制返回值：

javascript:void((function(){
  // 即使最后一行是有返回值的表达式，void 也会确保最终产出 undefined
  return document.querySelectorAll('img').length;
})());

此外，书签地址本质上是一个 URL 字符串。必须注意以下字符规范：

• 清除换行符与单行注释：书签必须保持在一行内执行。若代码中存在 // 这是注释，一旦换行被抹平，该行之后的所有代码都会被误当作注释而失效。因此代码应使用 /* 块注释 */ 或在压缩时彻底剔除注释。
• 转义特殊字符：URL 中的 % 字符必须替换为 %25，否则浏览器在做 URL 解码时会抛出 URIError；CSS 选择器或十六进制颜色值中的 # 必须转义为 %23，否则浏览器会将其误识别为网页锚点并截断后续代码。

第 3 步：将代码保存至浏览器书签栏

在不同浏览器（如 Google Chrome、Microsoft Edge、Mozilla Firefox、Apple Safari）中，添加 Bookmarklet 的操作大同小异：

1. 使用快捷键调出浏览器书签栏（例如 Chrome/Edge 中按下 Ctrl + Shift + B 或 macOS 下按下 Cmd + Shift + B）。
2. 在书签栏空白区域点击鼠标右键，在弹出菜单中选择「添加网页」（或「添加书签」）。
3. 在弹出的配置弹窗中：
   • 名称：填写真实的功能名称，例如「高亮无 alt 图片」或「导出表格为 CSV」。
   • 网址 (URL)：清空原有的 https://，粘贴以 javascript: 开头的整行转码脚本。
4. 点击「保存」，书签栏上即可出现对应的可点击按钮。

第 4 步：在目标网页一键触发并校验

打开任意需要处理的目标网站，直接在书签栏单击刚才创建的书签。可以先按 F12 打开浏览器开发者工具（DevTools）的「Console」面板，观察是否有你预设的日志输出或是否有脚本运行报错。

三、两类核心编写模式与完整代码实战

根据功能的复杂度以及代码量，Bookmarklet 的编写通常分为两种经典架构模式：自包含纯内联模式 与 动态外部脚本加载器模式。

模式一：自包含纯内联模式（适合轻量工具）

如果脚本逻辑在 50~100 行以内，不依赖外部大型类库，直接将所有逻辑写在书签 URL 中是最可靠的做法。这种模式执行速度极快，无需网络请求，且能天然绕过绝大多数网站对外部脚本域名的限制。

实战示例：一键高亮页面中所有未填写 alt 属性的图片，并在右下角统计数量

开发阶段的易读源码：

(function () {
  const missingImgs = Array.from(document.querySelectorAll('img')).filter(img => !img.hasAttribute('alt') || img.alt.trim() === '');
  if (missingImgs.length === 0) {
    alert('当前页面所有图片均已设置 alt 属性！');
    return;
  }

  // 给缺失 alt 的图片添加红色醒目边框
  missingImgs.forEach((img, index) => {
    img.style.outline = '4px solid #E53935';
    img.style.outlineOffset = '2px';
  });

  // 在页面右下角插入临时悬浮提示框
  const badge = document.createElement('div');
  badge.id = '__bookmarklet_img_counter';
  badge.style.position = 'fixed';
  badge.style.right = '20px';
  badge.style.bottom = '20px';
  badge.style.zIndex = '999999';
  badge.style.padding = '12px 18px';
  badge.style.background = '#24384C';
  badge.style.color = '#FFFFFF';
  badge.style.borderRadius = '8px';
  badge.style.fontSize = '14px';
  badge.style.boxShadow = '0 4px 12px rgba(0,0,0,0.15)';
  badge.innerText = '已标记 ' + missingImgs.length + ' 处未设置 alt 的图片 (点击关闭)';
  badge.onclick = function() {
    badge.remove();
    missingImgs.forEach(img => img.style.outline = '');
  };
  document.body.appendChild(badge);
})();

最终单行转码后的 Bookmarklet 交付代码：

javascript:(function()%7Bconst%20e=Array.from(document.querySelectorAll("img")).filter(e=>!e.hasAttribute("alt")%7C%7C""===e.alt.trim());if(0===e.length)return void%20alert("当前页面所有图片均已设置%20alt%20属性！");e.forEach(e=>%7Be.style.outline="4px%20solid%20%23E53935",e.style.outlineOffset="2px"%7D);const%20t=document.createElement("div");t.id="__bookmarklet_img_counter",t.style.position="fixed",t.style.right="20px",t.style.bottom="20px",t.style.zIndex="999999",t.style.padding="12px%2018px",t.style.background="%2324384C",t.style.color="%23FFFFFF",t.style.borderRadius="8px",t.style.fontSize="14px",t.style.boxShadow="0%204px%2012px%20rgba(0,0,0,0.15)",t.innerText="已标记%20"+e.length+"%20处未设置%20alt%20的图片%20(点击关闭)",t.onclick=function()%7Bt.remove(),e.forEach(e=>e.style.outline="")%7D,document.body.appendChild(t)%7D)();

模式二：动态外部脚本加载器模式（适合复杂工程）

当需求变得复杂（例如需要在页面中引入外部工具条、渲染复杂的统计图表、甚至引入 jQuery、vConsole 等现成库）时，书签栏的几千字符限制和编码管理就会成为瓶颈。此时，最佳实践是编写一个微型加载器（Loader），通过书签在宿主页面的 <head> 中动态插入一个 <script> 标签来异步拉取外部托管的完整 JS 脚本。

实战示例：安全动态载入外部脚本并附带防重入与缓存穿透机制

javascript:(function() {
  const SCRIPT_ID = '__my_injected_tool_v1';
  const SCRIPT_URL = 'https://example.com/cdn/my-helper.js';

  // 1. 检查是否已经注入，避免重复拉取
  if (document.getElementById(SCRIPT_ID)) {
    console.warn('工具脚本已经加载完毕，无需重复注入。');
    return;
  }

  // 2. 动态创建 script 节点
  const scriptNode = document.createElement('script');
  scriptNode.id = SCRIPT_ID;
  scriptNode.type = 'text/javascript';
  // 加上时间戳防止浏览器强缓存阻碍调试更新
  scriptNode.src = SCRIPT_URL + '?_t=' + Date.now();
  
  // 3. 监听加载完成事件
  scriptNode.onload = function() {
    console.log('外部脚本加载完成，初始化环境...');
    if (typeof window.MyCustomHelperInit === 'function') {
      window.MyCustomHelperInit();
    }
  };

  scriptNode.onerror = function() {
    console.error('加载外部脚本失败，可能受到 CSP 限制或网络不可达。');
    scriptNode.remove();
  };

  // 4. 挂载到文档树触发下载
  (document.head || document.documentElement).appendChild(scriptNode);
})();

四、核心限制与避坑指南

在实际使用中，许多初学者经常遇到“点击书签没有任何反应”或者“控制台报错”的问题，这通常是由以下几个关键安全机制与环境限制引起的：

限制场景	典型表现	根因分析	对应解决方案
内容安全策略 (CSP) 拦截	控制台红字报错：Refused to load the script ... because it violates Content Security Policy	目标网站配置了严格的 HTTP 响应头 Content-Security-Policy: script-src 'self'，禁止从外部域名动态拉取脚本	改用模式一（纯内联脚本）将逻辑写在书签内；若网站甚至禁止了 unsafe-inline，Bookmarklet 将被完全禁用，此时必须改用浏览器扩展（Extension）。
页面内容被字符串清空	点击后页面全白，整个视口只显示一个数字、布尔值或字符串	代码末尾的语句返回了非 undefined 的有效值，浏览器触发了原生的页面替换机制	使用 (function(){ ... })() 封闭逻辑，或在整体表达式前追加 void(...) 强制转换为 undefined。
代码因换行被截断	点击后无任何反应，语法错误 Uncaught SyntaxError: Unexpected end of input	源码中包含单行注释 //，保存至书签时被浏览器合并为一行，导致后续所有代码被整段注释	在压缩代码时删除全部单行注释，或严格改用 /* */ 多行块注释语法。
混合内容拦截 (Mixed Content)	在 HTTPS 页面中点击无效，控制台提示阻止了不安全的 HTTP 请求	宿主页面运行在 https:// 协议下，而动态注入的外部脚本地址采用了 http:// 协议	外部托管资源必须始终配置 https:// 证书，且引用时使用相对协议或确定的 HTTPS 协议。
浏览器内置特权页受限	在 chrome://、edge://、about:blank 或应用商店页面点击完全无效	出于浏览器沙箱防护机制，浏览器严格禁止任何脚本在管理页与扩展商店上下文中注入执行	属于安全常态，换用任意正常的外部网络页面（如 https://www.example.com）测试即可。

五、全景排查总结与快速自检清单

完成一个 Bookmarklet 的编写并准备投入日常使用前，请对照以下四个维度的自检矩阵进行核对：

1. 闭包与作用域：是否已用 (function(){ ... })() 隔离？是否杜绝了污染宿主页 window 的全局变量？末尾是否保证返回 undefined？
2. 转码与格式：是否排除了未封闭的 // 注释？是否转义了 %（转为 %25）和 #（转为 %23）？
3. 防御与容错：关键的 DOM 查询与网络请求是否包裹在 try...catch 中？DOM 是否添加了防重入检测（避免多次点击生成多个重复弹窗）？
4. UI 交互体验：提示信息建议动态插入轻量级浮层或控制台输出，尽量避免使用会阻塞主线程的同步 alert() 弹窗。