Tampermonkey 入门：安装、面板、新建脚本

从这一篇开始进入油猴脚本的实操。目标很朴素：装好 Tampermonkey，认识它的面板，写下并运行你的第一个用户脚本。全程不超过十分钟。

安装

Tampermonkey 在 Chrome Web Store、Edge 加载项商店、Firefox Add-ons 都有官方发布，直接搜名字安装即可。安装后工具栏会出现一块黑底白字的方形图标。注意区分：它是「管理器」，本身不改变任何网页；改变网页的是你之后往里装的脚本。

Chrome 用户如果遇到「已停用」提示（早期 Chrome 曾对新版管理器有兼容开关，路径在 chrome://extensions 的 Tampermonkey 详情页里），确保没有开启会影响它的实验性开关即可。浏览器版本更新频繁，具体以当前官方说明为准。

面板导览

点击工具栏图标，弹出的面板分几块。最上面是「当前正在运行的脚本」列表——你打开某个网页时，凡是匹配它的脚本都在这里，旁边有开关，点一下就禁用，再点恢复。这就是排错的第一现场：某个页面行为诡异，先来这里看看是不是脚本打架。

面板菜单里最常用的三项：

• 添加新脚本：打开内置编辑器，新建空脚本；
• 管理面板：所有脚本的完整列表，可编辑、导出、按站点启停；
• 实用工具：导入导出、云端同步备份脚本。

管理面板里每个脚本显示启用状态、版本、更新时间和匹配站点。脚本多了以后建议用「设置」里的排序和分组功能整理，否则找一个老脚本要翻很久。

第一个脚本

点「添加新脚本」，编辑器里会自动生成一个元数据模板，填成这样：

// ==UserScript==
// @name        页面标题时间戳
// @namespace   local.demo
// @version     0.1
// @description 在控制台打印当前页面的标题与加载时间
// @match       https://example.com/*
// @grant       none
// ==/UserScript==

(function () {
  "use strict";
  console.log("[脚本]", document.title, new Date().toLocaleTimeString());
})();

按 Ctrl+S 保存（编辑器也支持自动保存），切到匹配的网页刷新，按 F12 看 Console，应该能看到一行 [脚本] Example Domain 22:41:03 之类的输出。没看到就按顺序查三件事：脚本是否启用、URL 是否真的匹配 @match 规则、Console 有没有报错。

这里有两处细节值得说明。namespace 是脚本的唯一标识前缀，配合 @name 一起决定脚本身份，随意但要保持稳定，更新脚本时别改动这两项，否则管理器会当成两个脚本。IIFE 包裹加 "use strict" 是社区惯例，避免变量泄漏到隔离环境之外。

脚本即文本：安装与分享

用户脚本没有安装包的概念。朋友发你一个 .user.js 文件，或你在网页上点开一个以 .user.js 结尾的链接，Tampermonkey 会自动弹出安装页，展示元数据与代码，确认后落库。反过来，把你写好的脚本贴到 Greasy Fork 或 GitHub Gist，别人也能一键安装。这种「纯文本即软件」的分发方式是用户脚本生态独有的轻巧。

也正因为没有审核，安装来源不明的脚本前务必检查元数据的 @match 范围和代码里的跨域请求。安全习惯在第一章讲过，这里再强调一次：装脚本等于给作者一段浏览器的执行权。

管理面板的进阶功能

日常只用到面板的两成功能，但下面几项在脚本多了之后非常有用：

• 排序与搜索：管理面板顶部可按名称、安装时间、上次更新排序，右上角搜索框支持按名称与站点过滤；
• 按站点启停：面板列表里每个正在运行的脚本都有独立开关，且支持「仅在当前站点禁用」，比全局禁用精细；
• 实用工具页：导入导出 zip、URL 导入、云端备份（支持部分网盘与 Gist 同步），换机器不丢脚本全靠它；
• 设置里的更新策略：可配置自动检查更新的频率，也可以对单个脚本关闭自动更新（给改过代码的脚本关掉，防止自己的修改被上游覆盖）。

还有一个隐藏操作：脚本编辑器右侧的「设置」标签里可以调整缩进、主题，写长脚本前先调顺手。编辑器对保存有校验，元数据块格式错了会提示，这也是检查头部写法的快捷方式。

脚本更新与版本流转

管理器如何知道脚本该更新了？机制是：脚本头部 @updateURL / @downloadURL 指向的地址（未指定时用安装来源）会定期被检查，远端元数据里的 @version 大于本地即提示更新。这就是为什么上一节强调版本号纪律——你在 Greasy Fork 上改了代码不改版本号，已安装的用户永远收不到更新。

自己迭代脚本的推荐流程：本地改代码 → 版本号 +0.0.1 → 上传到发布渠道 → 用户的 Tampermonkey 在下次检查时自动拉新。整个链路没有任何「推送」动作，全靠版本号比较，理解了这一点，「用户说我的更新没生效」时你就知道先查版本号。

调试第一个脚本的完整流程

脚本没跑起来时，按这个顺序查，命中率很高：

1. 管理面板确认脚本开关是绿的；
2. 面板列表里确认「当前正在运行」区域出现了它——没出现就是 URL 不匹配，回去查 @match；
3. 目标页 F12 看 Console 有没有红色报错——语法错误会在这里现形；
4. 有输出但行为不对——在代码里加 console.log 二分定位，油猴编辑器保存即生效，迭代很快。

一个排查技巧：把 @match 先放宽成 *://*/*（全网匹配）验证脚本本体没问题，再逐步收窄到目标站点。这样能把「脚本问题」和「匹配问题」两类故障干净地分离。

小结与预告

跑通第一个脚本后，你会立刻遇到三个问题：@match 的规则到底怎么写、@grant none 是什么意思、想存点数据用什么 API。这正是接下来两篇的内容：先逐个讲透元数据头，再速成 GM_* API。

脚本里的文本处理和 URL 匹配大量用到正则，正则匹配写法可参考本站《正则表达式从入门到精通》：正则实战。如果你习惯在 HBuilderX 里写代码再粘进油猴编辑器，工程组织和语法提示都会舒服很多，见 HBuilderX 效率技巧。

安装渠道与安全说明

Tampermonkey 只应从官方渠道安装：Chrome Web Store、Edge 加载项、Firefox Add-ons（AMO）以及官网下载。第三方下载站的「Tampermonkey」可能是打包了恶意代码的仿冒版本，用户脚本管理器恰好是权限极高的扩展类型，装错仿冒版的代价远大于省下的几分钟。安装后可以在管理器「设置 → 版本」页确认版本号，与官网发布记录对照。

另一个安全常识：管理器会随浏览器启动常驻运行，如果某个时期你完全不用脚本，禁用它对浏览器性能有可感知的收益；需要时再启用，脚本与设置都会保留。

与扩展开发者模式的关系

Tampermonkey 本身就是一个扩展，它管理脚本的能力来自扩展体系（这正是它能在 Chrome 商店上架的原因）。理解这层关系有两个实用推论：其一，chrome://extensions 里 Tampermonkey 被禁用时，所有脚本全部失效，排查「脚本突然全挂了」先查这里；其二，脚本能力的天花板由管理器的扩展权限决定，Tampermonkey 申请了相当宽的权限来换取 GM API 的能力，这也是它偶尔被安全研究讨论的原因——理解了这一点，你就理解了脚本生态「便利与风险同源」的本质。

安装渠道、面板结构、第一个脚本、调试流程——这一篇的四个动作做完，你就拥有了完整的脚本开发回路，后面的内容都是在这个回路上加深度。

建议今天就把备份导出做一次——脚本库的第一次备份永远值得在学会写脚本之前完成。

顺手把今天写的第一个脚本导出一份存档：管理面板选中它，导出 zip，放进你的项目目录。从这个小小的存档开始，你就有了自己的脚本资产库——之后每写一个脚本都入库存档，一年后回看，这份资产库就是你在浏览器自动化领域积累的最直观证据。

最后留一个观察任务给你：打开管理面板看看 Tampermonkey 自己申请了哪些权限，再想想哪些对应你听过的 GM API——这一眼会让你对「能力来自权限」这句话有具体的认识。

面板状态速查

再看一个「最小可用」的行为验证脚本，用于确认管理器工作正常：

// ==UserScript==
// @name     环境自检
// @match    *://*/*
// @grant    none
// ==/UserScript==
console.log("[自检] 管理器注入正常", location.href);

全网匹配只做日志输出，安全无害，装上后随便开个网页看 Console 即可确认链路通畅，验证完记得停用或删除。

本章由 WorkBuddy 原创整理，API 行为依据 Chrome 扩展官方文档（Manifest V3）。