tampermonkey

Tampermonkey 用户脚本开发

用户脚本是用于修改网页和自动执行任务的浏览器脚本。

快速入门模板

JavaScript（不使用 GM. API 的简单脚本）*

// ==UserScript==
// @name         My Script Name                    // <- CUSTOMISE: Unique script name
// @namespace    https://example.com/scripts/      // <- CUSTOMISE: Your unique namespace
// @version      1.0.0                             // <- INCREMENT on updates
// @description  Brief description of the script   // <- CUSTOMISE: What it does
// @author       Your Name                         // <- CUSTOMISE: Your name
// @match        https://example.com/*             // <- CUSTOMISE: Target URL pattern
// @grant        none                              // <- ADD permissions as needed
// @run-at       document-idle                     // <- ADJUST timing if needed
// ==/UserScript==

(function() {
    'use strict';
    // Your code here
})();

现代写法（async/await——使用 GM. API 时推荐）*

// ==UserScript==
// @name         My Script Name
// @namespace    https://example.com/scripts/
// @version      1.0.0
// @description  Brief description of the script
// @author       Your Name
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.setValue
// @run-at       document-idle
// ==/UserScript==

(async () => {
    'use strict';
    // Async entry point - use await with GM.* APIs
    const setting = await GM.getValue('myKey', 'default');
    console.log('Script loaded, setting:', setting);
})();

**TypeScript：**添加 @types/tampermonkey 以获得完整的类型安全支持。参见 typescript.md。

---

必需的头部标签

标签	必需	用途	示例
@name	是	脚本名称（支持通过 :locale 实现国际化）	@name My Script
@namespace	推荐	唯一标识符命名空间	@namespace https://yoursite.com/
@version	是*	用于更新的版本号（*自动更新时必需）	@version 1.2.3
@description	推荐	脚本的功能	@description Enhances page layout
@match	是**	要运行脚本的 URL（**也可使用 @include）	@match https://example.com/*
@grant	视情况而定	API 权限（不使用 GM_* API 时设为 none）	@grant GM_setValue
@run-at	可选	注入时机（默认为 document-idle）	@run-at document-start
@run-in	可选	限定在普通或隐身标签页，或 Firefox 容器中运行（v5.3+）	@run-in normal-tabs

完整的头部文档参见：header-reference.md

---

URL 匹配快速参考

// Exact domain                  // @match https://example.com/*
// All subdomains                // @match https://*.example.com/*
// HTTP and HTTPS                // @match *://example.com/*
// Exclude paths (with @match)   // @exclude https://example.com/admin/*

高级模式（正则表达式、@include、特定路径）参见：url-matching.md

---

@grant 权限快速参考

需要执行的操作	授予的权限
存储持久化数据	@grant GM_setValue + @grant GM_getValue
发起跨域请求	@grant GM_xmlhttpRequest + @connect domain
添加自定义 CSS	@grant GM_addStyle
访问页面的 window	@grant unsafeWindow
显示通知	@grant GM_notification
添加菜单命令	@grant GM_registerMenuCommand
检测 URL 变化（SPA）	@grant window.onurlchange
批量读写设置（v5.3+）	@grant GM.getValues + @grant GM.setValues
静音/取消标签页音频	@grant GM_audio

// Disable sandbox (no GM_* except GM_info)
// @grant none

// Cross-origin requests require @connect
// @grant GM_xmlhttpRequest
// @connect api.example.com
// @connect *.googleapis.com

完整的权限指南参见：header-reference.md

---

@run-at 注入时机

值	脚本运行时机	用途
document-start	DOM 存在之前	阻止资源加载、尽早修改全局对象
document-body	body 存在时	尽早操作 DOM
document-end	DOMContentLoaded 时	适用于大多数脚本——DOM 已就绪
document-idle	DOMContentLoaded 之后（默认）	安全的默认选项
context-menu	右键菜单触发时	由用户触发的操作

---

常见模式

以下模式经常使用。下面是简要说明——如需查看包含代码示例的完整实现，请加载 patterns.md。

• 等待元素 - 基于 Promise 的 MutationObserver，当 CSS 选择器对应的元素出现在 DOM 中时解析，并可配置超时时间
• 检测 SPA URL 变化 - 使用 window.onurlchange 授权或拦截 History API 来检测单页应用中的导航
• 跨域请求 - 使用 GM_xmlhttpRequest 从外部 API 获取数据，并通过 @connect 对域名进行白名单设置。另请参阅 http-requests.md
• 添加自定义样式 - 使用 GM_addStyle 注入 CSS，以调整页面样式或隐藏元素。另请参阅 api-dom-ui.md
• 持久化设置 - 使用 GM_setValue/GM_getValue 存储用户偏好，并通过 GM_registerMenuCommand 提供切换选项。另请参阅 api-storage.md
• DOM 变更观察 - 使用 MutationObserver 监视动态添加的内容（包含防抖版本）
• 元素操作 - 注入 HTML、移除/隐藏元素，以及替换页面中的文本
• 键盘快捷键 - 简单的处理程序和支持修饰键的快捷键管理器
• 数据提取 - 将表格数据提取为数组/对象，收集并筛选页面链接
• 错误处理 - 用于 try/catch 的安全封装，以及带指数退避的异步重试
• TypeScript 用户脚本 - 使用 @types/tampermonkey 编写类型安全的脚本。请参阅 typescript.md

---

外部资源

// @require - Load external scripts
// @require https://code.jquery.com/jquery-3.6.0.min.js#sha256-/xUj+3OJU...
// @require tampermonkey://vendor/jquery.js         // Built-in library

// @resource - Preload and inject external CSS
// @resource myCSS https://example.com/style.css    // Then: GM_addStyle(GM_getResourceText('myCSS'))
// @grant GM_getResourceText
// @grant GM_addStyle

---

TypeScript 支持

安装类型定义，以获得完整的 IDE 自动补全和类型安全：

npm install --save-dev @types/tampermonkey

// ==UserScript==
// @name         My TypeScript Script
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.xmlHttpRequest
// @connect      api.example.com
// ==/UserScript==

(async () => {
    'use strict';
    const value = await GM.getValue<string>('key', 'default');
    const info: Tampermonkey.ScriptInfo = GM_info;
    console.log(info.script.name, value);
})();

使用打包工具（esbuild、Vite、webpack）构建为单个 .user.js 输出文件。有关完整的项目设置，包括 tsconfig 和打包工具配置，请参阅 typescript.md。

---

Tampermonkey 无法做到的事

用户脚本存在以下限制：

• 访问本地文件 - 无法读取/写入计算机上的文件
• 在页面脚本之前运行 - 在隔离沙盒模式下，页面脚本会先运行
• 访问跨域 iframe - 浏览器安全机制会阻止此操作
• 在不同机器间持久保存 - GM 存储仅限于各自的浏览器
• 绕过所有 CSP - 某些非常严格的 CSP 无法绕过
• 未经许可注入 - 在 Chrome 和 Edge 中，用户必须先在扩展程序详情页面启用“Allow User Scripts”切换项（较旧的浏览器则需启用 Developer Mode），脚本才能运行；脚本无法请求或绕过此要求。如果脚本始终未运行，请先检查这一项——请参阅 common-pitfalls.md 中的陷阱 15

大多数限制都有变通方法——请参阅 common-pitfalls.md。

---

生成用户脚本时

回复中始终包含：

1. 说明 - 脚本的功能（1-2 句话）
2. 完整用户脚本 - 包含所有头部信息的完整代码，并放在代码块中
3. 安装方法 - “复制/粘贴到 Tampermonkey 控制面板”或“另存为 .user.js”
4. 可自定义项 - 用户可以安全修改的内容（选择器、超时时间等）
5. 使用的权限 - 使用了哪些 @grants，以及需要它们的原因
6. 浏览器支持 - 仅支持 Chrome、仅支持 Firefox，还是通用

---

交付前检查清单

返回用户脚本之前，请确认：

关键项（必须通过）

• 未硬编码 API 密钥、令牌或密码
• @match 设置具体（不是 *://*/*）
• 所有外部 URL 均使用 HTTPS
• 插入 DOM 前已对用户输入进行清理

重要项（应当通过）

• 已用 IIFE 和 'use strict' 包装
• 所有 @grant 声明均为必要项
• @connect 包含所有外部域名
• 异步操作具备错误处理
• 操作 DOM 前进行了空值检查

推荐

• @version 遵循语义化版本规范（X.Y.Z）
• 兼容 Chrome 和 Firefox
• 注释解释不明显的代码

完整的安全检查清单请参见： security-checklist.md

---

参考文件指南

根据用户需求按需加载这些文件：

文件	加载时机
核心
header-reference.md	标头语法——所有 @tags 及示例
url-matching.md	@match、@include、@exclude 模式
patterns.md	常见实现模式及代码
sandbox-modes.md	安全/隔离执行上下文
API
api-sync.md	GM_* 同步函数参考（基于回调）
api-async.md	基于 Promise 的 GM.* API 参考——新脚本优先使用这些 API
api-storage.md	GM_setValue、GM_getValue、监听器
http-requests.md	GM_xmlhttpRequest 跨域请求
web-requests.md	GM_webRequest 拦截（Firefox）
api-cookies.md	GM_cookie 操作
api-dom-ui.md	addElement、addStyle、unsafeWindow
api-tabs.md	getTab、saveTab、openInTab
api-audio.md	静音/取消标签页静音
质量
common-pitfalls.md	导致脚本失效的问题及解决方法
debugging.md	如何调试用户脚本
browser-compatibility.md	Chrome 与 Firefox 的差异
security-checklist.md	交付前安全验证
version-numbering.md	版本字符串比较规则
typescript.md	使用 @types/tampermonkey 的 TypeScript 项目设置、打包器配置