Userscripts Safari用户脚本开发指南：从元数据到GM API深度解析

想要在Safari浏览器中轻松管理用户脚本吗？Userscripts Safari是专为iOS和macOS设计的开源用户脚本管理器，让你能够自由定制网页功能、优化浏览体验。本指南将带你从基础元数据到高级GM API，全面掌握用户脚本开发技巧。🚀

📝 用户脚本元数据完整指南

用户脚本的元数据块是脚本的"身份证"，位于脚本文件开头，用// ==UserScript==和// ==/UserScript==包裹。每个元数据标签都承载着特定的功能信息：

核心元数据标签详解：

• @name：脚本名称，显示在侧边栏并作为文件名
• @description：脚本功能描述，用户可设置隐藏显示
• @match：域名匹配模式，决定脚本在哪些网站运行
• @version：脚本版本号，配合@updateURL实现自动更新
• @grant：权限声明，控制脚本可使用的GM API方法

示例用户脚本结构：

// ==UserScript==
// @name        DEMO.Alert-URL
// @description Demo user script alert URL.
// @version     1.0.0
- @match        *://*/*
// @grant        none
// @inject-into  content
// @run-at      document-start
// ==/UserScript==

(function() {
    "use strict";
    // 你的脚本代码
})();

🔧 GM API方法深度解析

Userscripts支持丰富的GM API方法，让你的脚本拥有更强大的功能。所有方法都是异步的，使用时需要在@grant中声明。

数据存储API

• GM.setValue(key, value)：存储数据到本地
• GM.getValue(key, defaultValue)：读取存储的数据
• GM.deleteValue(key)：删除指定数据
• GM.listValues()：列出所有存储的键名

页面操作API

• GM.openInTab(url, openInBackground)：在新标签页打开链接
• GM.closeTab(tabId)：关闭指定标签页

网络请求API

• GM.xmlHttpRequest(details)：跨域网络请求
• GM.addStyle(css)：动态添加CSS样式

XMLHttpRequest使用示例：

const response = await GM.xmlHttpRequest({
    url: "https://api.example.com/data",
    method: "GET",
    headers: {"Content-Type": "application/json"}
});


⚙️ 高级配置与注入设置

注入上下文选择

通过@inject-into标签，你可以控制脚本注入的上下文：

• auto（默认）：由扩展自动选择
• content：内容脚本上下文，支持GM API
• page：页面上下文，受网站CSP限制

运行时机控制

• @run-at document-start：页面开始加载时
• @run-at document-end（默认）：页面加载完成时
• @run-at document-idle：页面空闲时

📁 脚本目录管理最佳实践

Userscripts允许你自定义脚本存储目录，实现跨设备同步：

• 默认目录：~/User/Library/Containers/Userscripts/Data/Documents/scripts

• 自定义目录：支持外部编辑器如VSCode、Sublime Text

重要提示： 更改脚本目录前，请关闭所有扩展界面实例。

💡 实用开发技巧与最佳实践

1. 脚本调试技巧

• 使用GM.info获取脚本运行信息
• 通过控制台查看脚本执行状态
• 利用浏览器开发者工具进行问题排查

2. 性能优化建议

• 合理使用@match和@include规则
• 避免不必要的GM API调用
• 优化脚本加载时机

3. 安全注意事项

• 谨慎使用@require加载远程资源
• 注意脚本权限控制
• 定期更新和维护脚本

🔍 常见问题解决方案

问题：遇到"Refused to execute a script"错误怎么办？ 这是网站内容安全策略（CSP）导致的，尝试设置@inject-into content来规避限制。

问题：是否需要使用扩展自带的编辑器？ 完全不需要！你可以使用任何外部代码编辑器，只要将文件保存到脚本目录即可。

通过掌握这些核心概念和实践技巧，你将能够轻松开发出功能强大的用户脚本，为Safari浏览器带来无限可能。记住，所有用户脚本都需要至少一个@match或@include规则才能运行！

想要开始你的用户脚本开发之旅吗？立即克隆项目仓库开始探索：

git clone https://gitcode.com/gh_mirrors/us/userscripts

开始你的Safari用户脚本开发之旅，打造个性化的网页浏览体验！✨