油猴脚本 `GM_*` 存储 API 教程与最佳实践

摘要
正在生成中……

油猴脚本（Tampermonkey、Greasemonkey 等）是功能强大的浏览器扩展，用于在网页上运行自定义的 JavaScript 脚本。GM_* 存储 API 是油猴脚本提供的一组专门用于数据存储的 API，可以在脚本中存储持久化数据。与浏览器的 localStorage 不同，GM_* API 的数据存储与网站域名无关，允许跨域共享数据，是开发复杂脚本的重要工具。

本文将介绍 GM_setValue、GM_getValue 等存储 API 的用法，并详细讲解在使用这些 API 时的最佳实践。

一、`GM_*` 存储 API 的用法

1. `GM_setValue` 和 `GM_getValue`

GM_setValue 用于保存数据，GM_getValue 用于读取数据。这些 API 不依赖于域名，因此可以在同一个油猴脚本中跨不同的域名使用共享的数据。

// 保存数据
GM_setValue('apikey', 'your_api_key_here');

// 获取数据
const apikey = GM_getValue('apikey');
console.log(apikey);  // 输出: your_api_key_here

这些 API 支持存储字符串、数字、布尔值等简单数据类型。如果要存储对象等复杂数据类型，则需要手动进行序列化和反序列化：

// 保存 JSON 对象
const user = { id: 123, name: 'John Doe' };
GM_setValue('userData', JSON.stringify(user));

// 获取并解析 JSON 对象
const storedData = JSON.parse(GM_getValue('userData'));
console.log(storedData.name);  // 输出: John Doe

2. 删除数据

你可以通过 GM_deleteValue 来删除某个存储值：

GM_deleteValue('apikey');

3. 异步和同步 API 差异

对于 Greasemonkey 4+，GM_* API 是异步的，返回 Promise，而在 Tampermonkey 中则是同步的。如果你需要兼容 Greasemonkey 4+，需要确保处理异步操作。

// 异步保存数据 (Greasemonkey 4+)
GM.setValue('apikey', 'your_api_key_here').then(() => {
    console.log('API Key saved');
});

// 异步获取数据 (Greasemonkey 4+)
GM.getValue('apikey').then((apikey) => {
    console.log(apikey);
});

二、最佳实践

1. 存储空间限制

虽然 GM_setValue 的存储容量比 localStorage 大，但它仍然有存储上限，且不同的脚本管理器有不同的存储限制。因此，避免存储过大数据（如图像或文件），只存储必要的信息。

2. 结构化数据的存储

GM_* API 不直接支持对象类型，存储对象时需将其转换为字符串（如 JSON 格式），读取时再进行解析。

const settings = { theme: 'dark', fontSize: 14 };
GM_setValue('userSettings', JSON.stringify(settings));

// 读取和解析数据
const storedSettings = JSON.parse(GM_getValue('userSettings'));
console.log(storedSettings.theme);  // 输出: dark

3. 数据持久性管理

GM_setValue 保存的数据会一直存在，直到用户手动清除浏览器数据或通过脚本删除。因此，应避免存储无用数据，确保定期清理无效信息。

// 删除某个不再需要的存储值
GM_deleteValue('oldKey');

4. 脚本作用域与数据隔离

GM_setValue 和 GM_getValue 基于脚本的 @namespace 和 @name 进行数据隔离。即使在同一个域名下，两个不同的脚本也无法共享数据。因此，编写脚本时要确保脚本的 @namespace 和 @name 保持一致，以避免意外的数据丢失。

// @name MyScript
// @namespace http://example.com/myscript

确保 @namespace 和 @name 在脚本维护过程中保持一致。

5. 敏感数据的存储与加密

虽然 GM_setValue 的数据保存在油猴扩展的沙盒中，普通网站无法直接访问，但为了提高安全性，存储敏感信息（如 API key、用户凭证等）时，建议对数据进行加密。

例如，可以使用 CryptoJS 库来对数据进行加密和解密：

// 加密 API Key
const encryptedKey = CryptoJS.AES.encrypt('your_api_key_here', 'secret_passphrase').toString();
GM_setValue('apikey', encryptedKey);

// 解密 API Key
const storedKey = GM_getValue('apikey');
const decryptedKey = CryptoJS.AES.decrypt(storedKey, 'secret_passphrase').toString(CryptoJS.enc.Utf8);
console.log(decryptedKey);

6. 设置最小权限

为了减少安全风险，遵循最小权限原则，确保脚本只在必要的网站上运行。通过 @match 或 @include 精确指定脚本的作用域，避免脚本运行在不必要的域名上。

// @match https://example.com/*

7. 调试和日志输出

在开发和调试时，确保使用 console.log 或 alert 来检查 GM_setValue 和 GM_getValue 的输出，确保数据正确存储和读取。

const apikey = GM_getValue('apikey');
console.log(`Stored API Key: ${apikey}`);

油猴脚本管理器通常自带调试控制台，建议在控制台中查看脚本的执行情况。

8. 跨域使用数据

如果你的脚本需要在多个域名上使用相同的数据，例如在 www.example.com 和 example.com 上共享同一个 API key，确保脚本在不同的域名上运行时能访问同一份存储数据。

// @match http://example.com/*
// @match http://www.example.com/*

三、总结

油猴脚本的 GM_* 存储 API 提供了强大的功能，可以轻松实现跨域的数据共享和持久化存储。通过掌握 GM_setValue 和 GM_getValue 的用法，并遵循存储限制、数据加密、最小权限等最佳实践，能够有效保护敏感数据并提高脚本的稳定性和安全性。

无论是简单的配置信息存储，还是跨域使用共享数据，合理使用 GM_* 存储 API 能帮助你开发出更加安全、健壮的用户脚本。

热门关键词

一、GM_* 存储 API 的用法

1. GM_setValue 和 GM_getValue