cobalt 剪贴板粘贴修复指南：在 Firefox 中启用 dom.events.asyncClipboard.readText

本篇指南基于 cobalt 官方 自我排障文档 展开，聚焦一个具体故障：在较旧版本的 Firefox 浏览器中，cobalt 页面的「paste（从剪贴板粘贴）」按钮无法工作。读完本文，你将理解 cobalt 剪贴板按钮的前端实现原理（navigator.clipboard.readText() 调用链与错误分支），并掌握通过修改单条 about:config 高级偏好项 dom.events.asyncClipboard.readText 完成修复的完整操作步骤，以及修复后的验证方式。

需要说明的前提：从 Firefox 125 版本开始，剪贴板粘贴已默认支持。如果你使用的是最新版本的 Firefox，无需跟随本文操作；本文档面向仍在使用 125 以下版本、且希望保留该便捷功能的用户。

一、cobalt 的剪贴板按钮是如何工作的

要理解为什么 Firefox 会失败，先看 cobalt 前端是怎么读剪贴板的。

在页面渲染层，src/modules/pageRender/page.js 中生成了输入区下方的粘贴按钮：

<button id="paste" class="switch" onclick="pasteClipboard()" ...>📋 paste</button>

按钮点击后进入 src/front/cobalt.js 中的 pasteClipboard() 函数，其核心逻辑非常短：

const pasteClipboard = async() => {
    try {
        let clipboard = await navigator.clipboard.readText();
        let onlyURL = clipboard.match(/https:\/\/[^\s]+/g)
        if (onlyURL) {
            eid("url-input-area").value = onlyURL;
            download(eid("url-input-area").value);
        }
    } catch (e) {
        // ... 错误分支，见下文
    }
}

从源码结构看，整个链路是：

1. 调用浏览器 Clipboard API 的 readText() 读取剪贴板最新文本；
2. 用正则 https:\/\/[^\s]+/g 从中提取 URL——如果剪贴板内容里不含合法链接，cobalt 不会处理它（这与官方变更日志「if your clipboard's latest content isn't a valid url, cobalt won't process or paste it」的描述一致）；
3. 提取成功则直接回填输入框并调用 download()，一步完成「粘贴 + 触发下载」。

此外，src/front/cobalt.js 中注册了键盘快捷键：输入框未聚焦时直接按 D 键，效果等同于点击 paste 按钮。

错误分支：为什么 Firefox 会弹出特殊提示

pasteClipboard() 的 catch 块按错误信息内容区分了三类情况（src/front/cobalt.js）：

错误特征	触发条件	对应提示（en.json）
denied	用户拒绝了剪贴板权限弹窗	ClipboardErrorNoPermission：提示可到站点设置中开启剪贴板权限，或手动粘贴链接
dismissed（或 iOS 环境）	权限请求被忽略	不弹错，静默处理
function 且为 Firefox	readText 在当前 Firefox 中不可用（抛出的错误含 Function not implemented 类字样）	ClipboardErrorFirefox：直接引导用户阅读本排障文档中的修复步骤

也就是说，你在旧版 Firefox 里点 paste 按钮看到的那条「firefox 剪贴板读取被禁用，可按以下步骤修复」提示，不是 cobalt 主动阉割功能，而是它检测到 readText() 在旧 Firefox 上抛错后给出的定向指引——该错误文案中的链接正是指向本文对应的文档锚点。

变更日志（src/modules/changelog/changelog.json）中也记载过：「clipboard button exception has been redone to prepare for adoption of readtext clipboard api in firefox」，即 cobalt 早先就是为 Firefox 后续支持 readText API 预留了这条异常分支。而本文档的标题「older versions of firefox」正对应这一历史背景：旧版 Firefox 默认不允许网页读取剪贴板文本，需要通过一条高级偏好项手动打开。

二、修复步骤：修改一条 about:config 偏好项

全部修复只需要改动 about:config 中的一条偏好：dom.events.asyncClipboard.readText，将其从 false 改为 true。

⚠️ 警告（原文档强调）：在 about:config 中乱改其他偏好项可能弄坏你的浏览器。除非你清楚自己在做什么，否则不要编辑其他任何偏好项。

步骤 1：进入 about:config

在 Firefox 地址栏输入 about:config 并回车：

步骤 2：确认风险提示页面

Firefox 会显示安全警告（"Proceed with caution. Changing advanced configuration preferences can impact Firefox performance or security."），勾选警告选项后，点击右下角蓝色按钮 「Accept the risk and continue」：

步骤 3：搜索目标偏好项

在 about:config 顶部的搜索框中输入 dom.events.asyncClipboard.readText：

步骤 4：点击最右侧的切换按钮

搜索结果行最右端有一个开关（toggle）按钮，点击它：

步骤 5：确认值已变为 true

切换后，该偏好项的值应当从 false 变为 true：

步骤 6：回到 cobalt 验证

返回 cobalt 页面，刷新页面，再次按下 paste 按钮。这次应当能正常读取剪贴板中的链接并直接触发下载。

三、验证、替代方案与相关细节

验证方式

• 复制一个 cobalt 支持的服务链接（如 youtube.com、tiktok.com 等，完整支持列表见 README 中的 supported services 表格）到剪贴板；
• 刷新 cobalt 页面后点击 📋 paste 按钮（或按 D 快捷键），若链接自动回填并进入下载流程，即修复成功；
• 若剪贴板里没有任何 https:// 链接，cobalt 按源码逻辑不会做任何事，属正常行为。

不想改浏览器设置？官方给出的替代路径

从 en.json 的两条错误文案看，cobalt 对无法读取剪贴板的用户都保留了退路：

• 手动粘贴：直接把链接粘贴进输入框，不依赖任何权限或高级偏好项；
• 站点权限：若提示是 ClipboardErrorNoPermission（denied 错误），说明是权限弹窗被拒绝，可到浏览器站点设置中启用剪贴板权限，无需动 about:config。

附带发现：另一个 Firefox 版本兼容开关

从源码结构看，cobalt 还针对更老的 Firefox 做了 UI 层兼容：src/front/cobalt.js 通过 UA 解析出 isOldFirefox（主版本号小于 103 的 Firefox），并在 src/front/cobalt.js 中为这类浏览器自动添加 no-transparency 类以关闭透明效果。这与本文的剪贴板问题相互独立——它只影响外观渲染，不影响 paste 功能，但说明 cobalt 对 Firefox 的版本差异有多处专门处理。

四、参考文件

路径	说明
docs/troubleshooting.md	本文对应的官方自我排障文档（标注 work-in-progress，后续会补充更多指南）
src/front/cobalt.js	pasteClipboard() 实现：readText → 正则提取 URL → 自动下载，及三类错误分支
src/modules/pageRender/page.js	paste 按钮的渲染位置
src/localization/languages/en.json	Firefox / 无权限两种剪贴板错误提示文案
docs/api.md、docs/run-an-instance.md	如果你自托管 cobalt 实例（paste 按钮行为在自托管实例上完全一致），可参考这两篇文档

修复完成后，cobalt 的「复制链接 → 一键粘贴下载」体验即可在旧版 Firefox 上完整恢复。