Tampermonkey 脚本头部元数据参考

Tampermonkey Userscript 油猴
技术教程
发布日期:   2026-05-12
文章字数:   4.3k
阅读时长:   16 分
阅读次数:  

Tampermonkey 脚本头部元数据参考

一、元数据块概述

脚本头部的 // ==UserScript== 块是油猴（Tampermonkey）脚本的标准配置清单，所有内容都是给油猴扩展程序读取的指令，不会被浏览器直接执行。它告诉油猴如何加载、运行、管理和更新这个脚本。

格式要求

  • 必须以 // ==UserScript== 开头，以 // ==/UserScript== 结尾
  • 每行格式为 // @指令名 指令值（指令名不区分大小写，值区分大小写）
  • 同一指令可以出现多次（如 @match、@grant）
  • 注释行以 // 开头，不能和指令在同一行

完整示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// ==UserScript==
// @name         B站视频字幕提取器
// @name:zh-CN   B站字幕提取器
// @name:en      Bilibili Subtitle Extractor
// @namespace    https://blog.qitongtingyu.online/
// @version      1.2.1
// @description  提取B站视频字幕，支持10种格式导出和搜索定位
// @description:en Extract subtitles from Bilibili videos
// @author       栖桐听雨
// @match        https://www.bilibili.com/video/*
// @exclude      https://www.bilibili.com/video/BV1xx411c7mZ
// @run-at       document-end
// @grant        GM_xmlhttpRequest
// @grant        GM_setClipboard
// @grant        GM_setValue
// @grant        GM_getValue
// @connect      api.bilibili.com
// @require      https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js
// @icon         https://www.bilibili.com/favicon.ico
// @homepageURL  https://github.com/qitongtingyu/bili-subtitle
// @supportURL   https://github.com/qitongtingyu/bili-subtitle/issues
// @updateURL    https://raw.githubusercontent.com/qitongtingyu/bili-subtitle/main/script.user.js
// @downloadURL  https://raw.githubusercontent.com/qitongtingyu/bili-subtitle/main/script.user.js
// @license      MIT
// ==/UserScript==

二、完整元数据指令分类详解

2.1 基础信息类

用于标识脚本的基本信息，在油猴管理面板中展示。

指令语法核心作用示例注意事项
@name@name 脚本名称脚本显示名称@name B站视频字幕提取器支持多语言：@name:zh-CN、@name:en
@namespace@namespace 命名空间唯一标识脚本@namespace https://github.com/...使用域名、GitHub 地址或邮箱
@version@version 版本号版本管理与更新检测@version 1.2.1推荐语义化版本
@description@description 功能描述脚本功能介绍@description 提取B站视频字幕...支持多语言
@author@author 作者名标注开发者@author 栖桐听雨多作者用逗号分隔
@icon@icon 图标URL显示图标@icon https://www.bilibili.com/...推荐 16x16 或 32x32 PNG/ICO
@icon64@icon64 64x64图标URL高清图标@icon64 https://example.com/icon64.png优先使用 64x64 像素
@homepageURL@homepageURL 主页URL官方主页@homepageURL https://github.com/...替代旧版 @homepage
@supportURL@supportURL 反馈URL用户反馈链接@supportURL https://github.com/.../issues通常是 GitHub Issues
@contributionURL@contributionURL 捐赠URL捐赠链接@contributionURL https://paypal.me/...支持 PayPal、支付宝
@license@license 许可证开源许可证@license MIT常见：MIT、GPL-3.0
@copyright@copyright 版权声明版权信息@copyright 2025 栖桐听雨说明版权归属
@tag@tag 标签名添加分类标签@tag 视频 @tag 字幕Greasy Fork 平台专用

2.2 运行控制类

控制脚本在哪些页面、什么时候运行，是最核心的配置之一。

指令语法核心作用示例注意事项
@match@match URL模式指定运行页面（推荐）@match https://www.bilibili.com/video/*规则严格，安全高
@include@include URL模式指定运行页面（兼容旧版）@include https://*.bilibili.com/*规则宽松，易被利用
@exclude@exclude URL模式排除不运行页面@exclude https://www.bilibili.com/video/BV1xx411c7mZ优先级高于 @match/@include
@noframes@noframes禁止在 iframe 运行@noframes避免重复运行
@run-at@run-at 时机指定运行阶段@run-at document-end可选：document-start/document-end等
@run-in@run-in 标签页类型指定标签页类型@run-in normal-tabsv5.3+，可选：normal-tabs/private-tabs/incognito
@inject-into@inject-into 上下文指定注入环境@inject-into content可选：page/content/auto
@sandbox@sandbox 沙箱模式指定沙箱环境@sandbox JavaScriptTampermonkey 4.18+，可选：JavaScript/DOM/raw

@match URL 模式语法详解

@match 的 URL 格式为 <protocol>://<domain><path>：

部分说明示例
protocol协议部分，* 可匹配 http 和 httpshttp*:// 匹配 http 和 https
domain域名部分，支持 * 通配符*.bilibili.com 匹配所有子域名
path路径部分，* 匹配任意字符/video/* 匹配所有视频页面

支持的协议：

  • http://
  • https://
  • http*://（匹配 http 和 https）

2.3 权限与安全类

声明脚本需要使用的油猴 API 权限和允许访问的外部资源，遵循最小权限原则。

指令语法核心作用示例注意事项
@grant@grant API名称申请使用油猴提供的特殊 API@grant GM_xmlhttpRequest没有声明的 API 无法使用，多个权限需要多次声明
@connect@connect 域名允许脚本向指定域名发送跨域请求@connect api.bilibili.com必须配合 @grant GM_xmlhttpRequest 使用
@require@require JS库URL引入外部 JavaScript 库@require https://cdn.jsdelivr.net/npm/jquery...油猴会缓存库文件，不会每次都下载
@resource@resource 资源名 资源URL引入外部资源（图片、CSS、文本等）@resource style https://example.com/style.css通过 GM_getResourceURL() 或 GM_getResourceText() 使用
@nocompat@nocompat 脚本管理器指定不兼容的脚本管理器@nocompat Greasemonkey避免脚本在不支持的管理器中运行
@webRequest@webRequest URL模式声明需要拦截的网络请求@webRequest https://*.bilibili.com/api/*需要配合 @grant GM_webRequest 使用

常用 @grant API 列表

API 名称功能
GM_xmlhttpRequest发送跨域 HTTP 请求
GM_setClipboard写入系统剪贴板
GM_setValue / GM_getValue / GM_deleteValue / GM_listValues持久化存储数据
GM_setValues批量设置存储数据（v5.3+）
GM_notification显示桌面通知
GM_openInTab在新标签页打开链接
GM_download下载文件到本地
GM_addStyle向页面添加 CSS 样式
GM_addElement向页面添加 DOM 元素
GM_getResourceText / GM_getResourceURL获取外部资源
GM_registerMenuCommand / GM_unregisterMenuCommand在油猴菜单中添加/移除命令
GM_addValueChangeListener / GM_removeValueChangeListener监听存储值变化
GM_getTab / GM_saveTab / GM_getTabs标签页管理
GM_info获取脚本和浏览器信息
GM_log输出日志到油猴控制台
unsafeWindow访问页面的 window 对象
window.close / window.focus关闭/聚焦窗口
window.onurlchangeURL 变化事件
none不使用任何 GM API，脚本运行在页面上下文

@grant none 的特殊说明

使用 @grant none 时：

  • 脚本运行在页面的 JavaScript 上下文，而非沙箱环境
  • 可以直接访问页面的全局变量和函数
  • 可以使用页面的 jQuery 等库（如页面已加载）
  • 无法使用大部分 GM_* API
  • 页面脚本和油猴脚本之间没有隔离

2.4 更新与分发类

控制脚本的自动更新和分发渠道。

指令语法核心作用示例注意事项
@updateURL@updateURL 更新检测URL检查更新地址@updateURL https://raw.githubusercontent.com/.../script.user.js必须返回脚本原始内容
@downloadURL@downloadURL 下载URL新版本下载地址@downloadURL https://raw.githubusercontent.com/.../script.user.js与 @updateURL 相同可省略
@installURL@installURL 安装URL官方安装地址@installURL https://greasyfork.org/scripts/...用于脚本分发平台

自动更新原理

  1. 油猴定期访问 @updateURL 获取脚本内容
  2. 对比脚本中的 @version 与本地版本
  3. 如果远程版本更高，提示用户更新
  4. 用户确认后，从 @downloadURL 下载新版本

补充说明：

  • 如果没有配置 @updateURL，油猴会尝试从脚本的安装地址检查更新
  • @downloadURL 可以是不同的地址，用于分流下载

2.5 高级功能类

一些不常用但功能强大的高级指令。

指令语法核心作用示例注意事项
@antifeature@antifeature 类型 描述声明脚本”反功能”@antifeature ads 脚本会显示非侵入式广告Greasy Fork 强制要求声明
@priority@priority 优先级指定运行优先级@priority 1数值越小优先级越高，默认 0
@preprocess@preprocess 预处理指令预处理方式@preprocess none可选：none/c-style/javascript
@unwrap@unwrap取消包装函数@unwrap已废弃

@antifeature 反功能类型

类型说明
ads脚本显示广告
tracking脚本包含追踪功能
miner脚本利用用户算力进行挖矿
payment脚本要求付费才能使用完整功能
data-collection脚本收集用户数据
referral脚本包含推荐/返利链接

注意：这是 Greasy Fork 平台的强制要求，其他脚本平台可能不要求。

三、重要指令深度解析

3.1 @match vs @include：为什么推荐用 @match

@match 是为了解决 @include 的安全问题而设计的，两者的通配符规则有本质区别：

特性@match@include
通配符 *只能匹配一个路径段，不能跨 /可以匹配任意字符，包括 /
安全性高，规则严格低，容易被恶意利用
示例匹配https://*.bilibili.com/* 不会匹配 https://bilibili.com.evil.com/*https://*.bilibili.com/* 会匹配 https://evil.com/?url=https://bilibili.com/

最佳实践：始终使用 @match 代替 @include
⚠️ 危险警告：永远不要使用 @include *，这会让脚本在所有页面运行，极其危险

恶意利用案例：
攻击者可以构造一个恶意网站 https://evil.com/?url=https://www.bilibili.com/，如果脚本使用 @include https://*.bilibili.com/*，这个恶意网址也会匹配成功。

3.2 @run-at 运行时机详解

时机说明适用场景
document-start页面开始加载时运行（最早）拦截请求、修改全局变量。限制：DOM 未加载，不能操作 DOM
document-endDOM 加载完成后运行（默认）操作页面 DOM 元素、添加按钮和事件
document-idle浏览器空闲时运行等待页面资源加载完成的场景，不阻塞加载
body<body> 标签出现时运行尽早操作 body 元素的场景
menu用户点击脚本菜单时运行脚本不自动运行，用户主动触发
context-menu用户右键点击脚本菜单时运行脚本不自动运行，右键菜单触发

推荐选择：

  • 大多数脚本使用 document-end 即可
  • 需要操作 DOM 元素时，明确指定运行时机
  • 避免使用默认值，确保脚本行为可预测

3.3 @connect 跨域白名单

  • 必须和 @grant GM_xmlhttpRequest 配合使用
  • 支持通配符：@connect *.bilibili.com 允许访问 bilibili.com 的所有子域名
  • 特殊值 self：允许请求当前页面的域名
  • 禁止使用 @connect *，这会给恶意脚本窃取数据大开方便之门

安全建议：

1
2
3
4
5
6
7
8
9
10
11
// ✅ 好的做法：指定具体域名
@connect api.bilibili.com
@connect *.bilibili.com

// ❌ 危险做法：允许所有域名
@connect *

**特殊值说明**：
- `localhost` / `127.0.0.1`：允许访问本地服务器
- `self`：允许请求当前页面的域名
- 如果需要访问端口号，必须明确指定，如 `@connect localhost:3000`

3.4 @inject-into 注入上下文选择

值说明适用场景
page注入到页面 JavaScript 上下文访问页面变量。限制：无法使用大部分 GM API
content注入隔离的内容脚本上下文更高安全性，与页面脚本隔离，变量不污染
auto自动选择（默认）大多数情况使用默认值

3.5 @sandbox 沙箱模式选择

值说明适用场景
JavaScriptJavaScript 沙箱中运行（默认）大多数脚本，推荐使用
DOM可访问 DOM，不能访问页面 JS 变量需要操作页面 DOM
raw最严格沙箱，只能访问 JS 核心 API，不能访问 DOM极少使用

四、元数据最佳实践

安全原则

  1. 使用 @match 代替 @include：严格的 URL 匹配规则能有效防止脚本在非预期页面运行
  2. 最小权限原则：只申请脚本实际需要的 @grant 和 @connect 权限
  3. 资源可信：@require 和 @resource 只使用来自可信来源的资源（如 jsDelivr、GitHub Raw）
  4. 避免通配符滥用：不要使用 @match * 或 @connect *
  5. 保护敏感信息：不要在元数据中包含敏感信息，如 API 密钥、密码等
  6. 使用 HTTPS：优先使用 HTTPS 协议的资源链接，避免 HTTP 被劫持
  7. 谨慎使用 unsafeWindow：可能被页面脚本攻击，尽量避免使用
  8. 配置 @webRequest 需谨慎：配合 @grant GM_webRequest 使用，可以拦截网络请求

规范建议

  1. 明确运行时机：不要依赖默认的 @run-at document-end，根据脚本功能明确指定
  2. 语义化版本号：使用语义化版本（主版本.次版本.修订号），每次更新递增版本号
  3. 完善元数据：提供清晰的 @description、@supportURL 和 @license
  4. 多语言支持：为 @name 和 @description 添加多语言版本

分发优化

  1. 配置更新地址：正确配置 @updateURL 和 @downloadURL，方便用户获取更新
  2. 添加标签：使用 @tag 指令为脚本添加分类标签，便于在脚本平台被发现
  3. 声明反功能：如果脚本包含广告或其他特殊功能，使用 @antifeature 如实声明

开发建议

  1. 使用模板：新建脚本时使用油猴内置模板，包含基本元数据
  2. 启用调试：在油猴设置中启用 “调试模式”，方便排查问题
  3. 版本管理：使用 Git 管理脚本版本，配合 @updateURL 实现自动更新

五、脚本安全检查清单

在安装或编写脚本时，务必检查以下元数据项：

  • @match/@include 只包含脚本需要运行的域名
  • @grant 只申请了必要的 API 权限
  • @connect 只包含脚本需要访问的域名
  • @require 和 @resource 来自可信来源
  • 检查脚本是否有 @antifeature 声明，如果有，确认你能接受这些功能
  • 版本号正确，更新地址可信
  • 检查脚本的大小，如果异常大，可能包含恶意代码

六、常见问题与解决方案

Q1：脚本没有在预期的页面运行？

可能原因：

  • @match 规则不正确
  • URL 中包含查询参数或哈希值
  • 页面在 iframe 中运行

解决方案：

  • 使用更宽松的 @match 规则（如 https://*.example.com/*）
  • 检查是否需要添加 @noframes 指令
  • 确认脚本已启用

Q2：跨域请求失败？

可能原因：

  • 没有声明 @connect 域名
  • 没有声明 @grant GM_xmlhttpRequest

解决方案：

  • 添加 @connect 目标域名
  • 添加 @grant GM_xmlhttpRequest

Q3：GM API 无法使用？

可能原因：

  • 没有在元数据中声明该 API
  • 使用了 @grant none，禁用了所有 GM API

解决方案：

  • 在元数据中添加对应的 @grant 声明
  • 如果需要使用 GM API，移除 @grant none

Q4：脚本更新不生效？

可能原因：

  • @updateURL 配置错误
  • 版本号没有递增
  • 缓存问题

解决方案：

  • 检查 @updateURL 是否返回正确的脚本内容
  • 确保版本号比当前版本高
  • 在油猴管理面板手动检查更新

Q5：脚本与页面脚本冲突？

可能原因：

  • 脚本运行在页面上下文，变量命名冲突
  • 页面脚本修改了关键对象

解决方案：

  • 使用 @inject-into content 隔离脚本环境
  • 使用立即执行函数（IIFE）避免全局污染
  • 使用唯一的前缀命名变量和函数

Q6：脚本运行缓慢怎么办？

可能原因：

  • 脚本在页面加载时执行了过多操作
  • 使用了 @run-at document-start 但进行了 DOM 操作

解决方案：

  • 使用 @run-at document-idle 避免阻塞页面加载
  • 将耗时操作延迟执行
  • 优化脚本代码，减少不必要的计算

Q7：脚本在某些浏览器中不工作？

可能原因：

  • 浏览器不支持 Tampermonkey
  • 脚本使用的 API 在该浏览器中不可用
  • 浏览器安全策略限制

解决方案：

  • 检查浏览器是否支持 Tampermonkey
  • 查看脚本使用的 GM API 是否在该浏览器中可用
  • 尝试使用兼容性更好的 API

七、GM API 快速参考

存储 API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// 设置值
GM_setValue("key", "value");
GM_setValues({ key1: "value1", key2: "value2" });

// 获取值
const value = GM_getValue("key", "defaultValue");

// 删除值
GM_deleteValue("key");

// 列出所有键
const keys = GM_listValues();

// 监听值变化
const listenerId = GM_addValueChangeListener(
  "key",
  (key, oldValue, newValue) => {
    console.log(`值从 ${oldValue} 变为 ${newValue}`);
  },
);
GM_removeValueChangeListener(listenerId);

网络请求 API

1
2
3
4
5
6
7
8
9
10
11
GM_xmlhttpRequest({
  method: "GET",
  url: "https://api.example.com/data",
  headers: { "Content-Type": "application/json" },
  onload: (response) => {
    console.log("响应:", response.responseText);
  },
  onerror: (error) => {
    console.error("请求失败:", error);
  },
});

UI API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// 添加样式
GM_addStyle(".example { color: red; }");

// 添加元素
const button = GM_addElement("button", {
  textContent: "点击我",
  className: "my-button",
});
button.onclick = () => alert("clicked!");

// 打开新标签页
GM_openInTab("https://example.com", { active: false });

// 显示通知
GM_notification({
  text: "操作完成",
  title: "提示",
  image: "icon.png",
  onclick: () => console.log("通知被点击"),
});

// 注册菜单命令
const menuId = GM_registerMenuCommand("我的命令", () => {
  console.log("命令被执行");
});
GM_unregisterMenuCommand(menuId); // 注销菜单命令

信息 API

1
2
3
4
5
// 获取脚本和浏览器信息
console.log(GM_info.script.name); // 输出脚本名称
console.log(GM_info.script.version); // 输出脚本版本
console.log(GM_info.script.author); // 输出脚本作者
console.log(GM_info.platform); // 输出浏览器平台信息

剪贴板 API

1
GM_setClipboard("要复制的内容", "text");

下载 API

1
2
3
4
5
6
7
GM_download({
  url: "https://example.com/file.pdf",
  name: "file.pdf",
  saveAs: true,
  onload: () => console.log("下载完成"),
  onerror: (error) => console.error("下载失败:", error),
});

八、总结

Tampermonkey 脚本头部元数据是脚本的核心配置，正确配置元数据能确保脚本安全、可靠地运行。

核心要点：

  1. 使用 @match 代替 @include，提高安全性
  2. 遵循最小权限原则，只申请必要的权限
  3. 明确指定运行时机，避免依赖默认值
  4. 配置正确的更新地址，方便用户获取更新
  5. 提供完整的元数据信息，便于脚本管理和分发
  6. 使用 @grant none 时要谨慎，确保不需要 GM API

通过掌握这些元数据指令，你可以编写出更加专业、安全的油猴脚本。

文章作者: 栖桐听雨声
文章链接: https://dfamemaster.github.io/post/tampermonkey-jiao-ben-tou-bu-yuan-shu-ju-can-kao
版权声明: 本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 栖桐听雨声 !
Tampermonkey Userscript 油猴
  目录