develop-userscripts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Develop Userscripts

开发用户脚本

Userscript work usually breaks at the runtime and metadata boundary, not in the page logic. Choose the runtime first, declare the minimum permissions up front, then debug in the environment where the script actually runs.

用户脚本开发中的问题通常出现在运行时和元数据边界，而非页面逻辑部分。请先选择运行时，提前声明最小必要权限，再在脚本实际运行的环境中调试。

When to Use

适用场景

Use this skill for:

writing or fixing a Tampermonkey or ScriptCat userscript
debugging injection timing, missing permissions, CSP workarounds, update checks, or
```
GM_*
```
behavior
deciding between a portable foreground script and ScriptCat-only
```
@background
```
or
```
@crontab
```
adding config UI with
```
==UserConfig==
```
packaging a ScriptCat
```
==UserSubscribe==
```
bundle or preparing a CloudCat-compatible script

Do not use this skill for full browser extension development or general browser automation outside userscript managers.

该技能适用于以下场景：

编写或修复Tampermonkey或ScriptCat用户脚本
调试注入时机、权限缺失、CSP绕过、更新检查或
```
GM_*
```
相关行为问题
在可移植前台脚本和仅ScriptCat支持的
```
@background
```
/
```
@crontab
```
脚本之间做选型
用
```
==UserConfig==
```
添加配置UI
打包ScriptCat
```
==UserSubscribe==
```
包或适配CloudCat的脚本

请勿将该技能用于完整浏览器扩展开发，或用户脚本管理器之外的通用浏览器自动化场景。

Runtime Selection

运行时选型

dot

digraph userscript_runtime {
    "Need page DOM or page context?" [shape=diamond];
    "Need persistent or scheduled work?" [shape=diamond];
    "Need to install many scripts as one package?" [shape=diamond];
    "Portable foreground script" [shape=box];
    "ScriptCat background or crontab script" [shape=box];
    "ScriptCat subscription package" [shape=box];

    "Need page DOM or page context?" -> "Portable foreground script" [label="yes"];
    "Need page DOM or page context?" -> "Need persistent or scheduled work?" [label="no"];
    "Need persistent or scheduled work?" -> "ScriptCat background or crontab script" [label="yes"];
    "Need persistent or scheduled work?" -> "Need to install many scripts as one package?" [label="no"];
    "Need to install many scripts as one package?" -> "ScriptCat subscription package" [label="yes"];
    "Need to install many scripts as one package?" -> "Portable foreground script" [label="no"];
}

dot

digraph userscript_runtime {
    "Need page DOM or page context?" [shape=diamond];
    "Need persistent or scheduled work?" [shape=diamond];
    "Need to install many scripts as one package?" [shape=diamond];
    "Portable foreground script" [shape=box];
    "ScriptCat background or crontab script" [shape=box];
    "ScriptCat subscription package" [shape=box];

    "Need page DOM or page context?" -> "Portable foreground script" [label="yes"];
    "Need page DOM or page context?" -> "Need persistent or scheduled work?" [label="no"];
    "Need persistent or scheduled work?" -> "ScriptCat background or crontab script" [label="yes"];
    "Need persistent or scheduled work?" -> "Need to install many scripts as one package?" [label="no"];
    "Need to install many scripts as one package?" -> "ScriptCat subscription package" [label="yes"];
    "Need to install many scripts as one package?" -> "Portable foreground script" [label="no"];
}

Preflight

前期检查

Confirm the manager and browser. On Manifest V3 browsers, ScriptCat may require
```
Allow User Scripts
```
or browser developer mode before scripts run.
Decide page script versus background script before writing code. ScriptCat background scripts cannot touch the DOM.
Start with metadata, not implementation:
```
@match
```
,
```
@grant
```
,
```
@connect
```
,
```
@run-at
```
, and any update URLs.
Prefer portable
```
==UserScript==
```
patterns for ordinary page scripts. Only switch to ScriptCat-only headers when the requested behavior actually needs them.

确认使用的脚本管理器和浏览器。在Manifest V3浏览器中，ScriptCat运行脚本前可能需要开启「允许用户脚本」选项或浏览器开发者模式。
编码前先确定是开发页面脚本还是后台脚本，ScriptCat后台脚本无法操作DOM。
从元数据而非业务逻辑开始开发：先配置
```
@match
```
、
```
@grant
```
、
```
@connect
```
、
```
@run-at
```
和所有更新链接。
普通页面脚本优先使用可移植的
```
==UserScript==
```
规范，只有当需求确实需要时才切换到ScriptCat专属的头字段。

Workflow

工作流

Choose the runtime and metadata first.
Declare the smallest permission surface that fits the task.
Implement against the runtime you chose.
Debug where the code really runs.
- Foreground scripts: page console plus manager logs.
- ScriptCat background scripts: run log first, then
```
background.html
```
  for real-environment debugging.
Publish with the right update model.
- Normal scripts: keep
```
@version
```
  accurate and add
```
@updateURL
```
  or
```
@downloadURL
```
  only when needed.
- Subscription bundles: use
```
==UserSubscribe==
```
  , HTTPS URLs, and subscription-level
```
@connect
```
  .

先确定运行时和元数据配置。
声明满足需求的最小权限范围。
基于所选运行时实现业务逻辑。
在代码实际运行的环境中调试。
- 前台脚本：页面控制台 + 脚本管理器日志
- ScriptCat后台脚本：先查看运行日志，再通过
```
background.html
```
  进行真实环境调试
按照合适的更新模式发布
- 普通脚本：保证
```
@version
```
  准确，仅在需要时添加
```
@updateURL
```
  或
```
@downloadURL
```
- 订阅包：使用
```
==UserSubscribe==
```
  、HTTPS链接和订阅级的
```
@connect
```
  配置

Quick Reference

快速参考

Intent	Default choice	Watch for
Page UI, DOM scraping, page patching	Portable `==UserScript==`	`@match` , `@grant` , `@run-at` , CSP-sensitive injection
Cross-origin API access	`GM_xmlhttpRequest` with explicit `@connect`	Missing hosts, cookie behavior differences, user authorization
Long-running worker	ScriptCat `@background`	No DOM, must return `Promise` for async work
Scheduled task	ScriptCat `@crontab`	Only first `@crontab` counts, prefer 5-field cron, avoid interval overlap
User-editable settings	`==UserConfig==` plus `GM_getValue`	Block placement and `group.key` naming
Silent bundle install and updates	`==UserSubscribe==`	HTTPS, `user.sub.js` , subscription `connect` overrides child scripts

用途	默认选型	注意事项
页面UI、DOM抓取、页面补丁	可移植 `==UserScript==`	`@match` 、 `@grant` 、 `@run-at` 配置、CSP敏感的注入场景
跨域API访问	搭配显式 `@connect` 配置的 `GM_xmlhttpRequest`	缺失主机配置、Cookie行为差异、用户授权问题
长时间运行的worker	ScriptCat `@background`	无DOM权限，异步任务必须返回 `Promise`
定时任务	ScriptCat `@crontab`	仅第一个 `@crontab` 配置生效，优先使用5字段cron表达式，避免区间重叠
用户可编辑配置	`==UserConfig==` + `GM_getValue`	块放置位置和 `group.key` 命名规范
静默安装和更新包	`==UserSubscribe==`	必须使用HTTPS、命名为 `user.sub.js` ，订阅级 `connect` 配置会覆盖子脚本配置

Common Mistakes

常见错误

Missing
```
@grant
```
for APIs the script actually uses.
Missing
```
@connect
```
for hosts used by
```
GM_xmlhttpRequest
```
or
```
GM_cookie
```
.
Treating
```
@include
```
as a better default than
```
@match
```
for ordinary host targeting.
Using DOM APIs inside ScriptCat background or cron scripts.
Returning from a ScriptCat background script before async GM work is truly finished.
Mixing
```
==UserScript==
```
and
```
==UserSubscribe==
```
packaging concepts.
Putting
```
==UserConfig==
```
in the wrong place or reading config keys without the
```
group.key
```
name.
Assuming Tampermonkey and ScriptCat storage, notification, or request behavior is identical.

脚本实际使用的API缺失对应的
```
@grant
```
声明
```
GM_xmlhttpRequest
```
或
```
GM_cookie
```
使用的主机缺失对应的
```
@connect
```
声明
普通主机匹配场景下优先使用
```
@include
```
而非更安全的
```
@match
```
在ScriptCat后台或定时脚本中使用DOM API
ScriptCat后台脚本中异步GM任务未完全完成就提前返回
混淆
```
==UserScript==
```
和
```
==UserSubscribe==
```
打包概念
```
==UserConfig==
```
放置位置错误，或未使用
```
group.key
```
格式读取配置键
假设Tampermonkey和ScriptCat的存储、通知、请求行为完全一致

References

参考资料

```
references/metadata-and-api-map.md
```
```
references/scriptcat-extensions.md
```

```
references/metadata-and-api-map.md
```
```
references/scriptcat-extensions.md
```