1. 从一行需求开始：这个按钮到底要处理什么
上个月给某内部工具加一个"复制本页链接"的小按钮。需求文档上就一行字，我当时的判断是三分钟收工：Vue 3 里调一下navigator.clipboard.writeText(window.location.href)，完事。结果那天下午从这个按钮里翻出来的问题，足够写满一整篇笔记——非安全上下文下 Clipboard API 直接是undefined、某社交 App 内置浏览器里写剪贴板的 Promise 永远挂着不 resolve、带访问凭证的地址被复制出去贴进了工单截图、hash 路由下的中文参数被二次编码成了乱码。一个"复制当前地址"的功能，表面是剪贴板调用，实际是浏览器能力探测 + 降级兜底 + URL 清洗 + 交互反馈四件事叠在一起。这篇就按我当时落地的顺序，把useClipboard封装、execCommand降级、安全过滤这三块拆开讲，代码都是能直接抄进项目的版本，顺带把踩过的坑一并交代清楚。
1.1 需求的表面描述和真实边界
产品说的是"复制链接"，但真正落到代码里，这个"链接"要回答一连串问题：复制的是location.href还是路由fullPath？带不带 hash？带不带查询参数？查询参数里哪些是页面状态、哪些是用户隐私？开发环境复制出来是localhost:5173，发给同事他打不开怎么办？用户在页面里滚动了半屏、切换了 tab，这些状态要不要编码进链接？
需求文档不会写这些，但每一个都会在联调时被打回来。我的习惯是先把这些边界在白板上列出来，再决定 API 长什么样。这一步省不得，等到写完 composable 再回头加参数，往往要把调用方全改一遍。
1.2 三条技术路线的取舍
能实现"写入剪贴板"的路径，掰着指头数就三条：
| 方案 | 能力来源 | 优点 | 硬伤 | 适用判断 |
|---|---|---|---|---|
navigator.clipboard.writeText | 异步剪贴板 API | 语义清晰、支持 Promise、不污染 DOM | 必须安全上下文，且需要用户激活 | 首选，覆盖绝大多数现代浏览器 |
document.execCommand('copy') | 传统编辑命令 | 兼容老浏览器和内嵌环境，理论上不需要安全上下文 | 已标记废弃、必须操作 DOM 选区、会打断用户当前选择 | 兜底，只在首选失败时启用 |
| 让用户手动选中复制 | 无 | 零依赖 | 体验灾难 | 前两条都失败时才提示 |
选型上没什么好纠结的：主路径走异步剪贴板 API，失败静默降级到execCommand，两条都挂掉再退回一句"请手动选中地址栏复制"。真正花时间的是降级路径的细节，以及"什么情况下该降级、什么情况下不该"的判断。
有一个判断值得单独说：NotAllowedError有两种来源，一种是页面没有获得用户激活（比如你在await一个接口之后才调写剪贴板），另一种是用户在权限弹窗里点了拒绝。前者降级到execCommand有时能救回来，后者救不回来。我采取的策略是一律先尝试降级，降级也失败再抛错——因为区分这两种错误在当前浏览器上并不可靠，多做一次尝试的成本几乎为零。
1.3 封装层的职责切分
我见过不少项目把复制逻辑直接写在按钮的@click里，一个组件几十行，改一次文案要动三个文件。这个功能虽然小，但它天然适合抽成组合式函数，理由有三点：
第一，状态和视图分离。按钮要显示"复制中/已复制/失败"，这些状态属于逻辑层，不该散落在模板的v-if里。第二，复用场景不止一个。除了复制当前地址，项目里还有复制订单号、复制邀请码、复制一段配置文本，它们的降级路径和错误处理完全一样，只有内容清洗规则不同。第三，便于测试。把写剪贴板的能力探测抽成独立函数，单元测试里可以直接打桩。
最终的职责切分是这样的：useClipboard只负责"把一段字符串塞进剪贴板"并且维护状态机；URL 清洗是另一个纯函数模块shareUrl.js；组件里只做一件事——点击时先算地址、清洗、再交给copy()。分层之后，每个文件都不超过一百行，改需求时心里有数。
2. 用 Composition API 把 Clipboard 包成可复用单元
2.1 useClipboard 的接口与状态机设计
先定接口再写实现。我想要的调用方式是const { status, copy, reset } = useClipboard()，status是一个只读的枚举值，copy返回 Promise ，调用方能根据返回值决定后续动作。状态机只有四个节点，够用且不会失控：
// composables/useClipboard.js import { ref, readonly, onScopeDispose } from 'vue' export const CopyStatus = Object.freeze({ IDLE: 'idle', COPYING: 'copying', SUCCESS: 'success', ERROR: 'error', }) export function useClipboard(config = {}) { const { resetDelay = 1800, // 成功态保持多久后自动回落 transform = (text) => text, // 写入前的最后一道加工 onSuccess, onError, } = config const status = ref(CopyStatus.IDLE) const error = ref(null) let timer = null function clearTimer() { if (timer) { clearTimeout(timer) timer = null } } function reset() { clearTimer() status.value = CopyStatus.IDLE error.value = null } async function copy(rawText) { clearTimer() status.value = CopyStatus.COPYING error.value = null let payload try { payload = await transform(rawText) } catch (e) { error.value = e status.value = CopyStatus.ERROR onError?.(e) return false } try { await writeClipboard(String(payload ?? '')) status.value = CopyStatus.SUCCESS onSuccess?.(payload) return true } catch (e) { error.value = e status.value = CopyStatus.ERROR onError?.(e) return false } finally { // 无论成败都安排回落，避免按钮卡在成功态 timer = setTimeout(reset, resetDelay) } } onScopeDispose(clearTimer) return { status: readonly(status), error: readonly(error), copy, reset, } }几个设计取舍值得说明。status用readonly包一层，是为了防止外部组件直接改状态绕过状态机——这种 bug 排查起来极痛苦，明明逻辑写对了按钮却一直显示"已复制"，最后发现是某个子组件v-model绑上去了。transform放在copy内部而不是调用方，是因为"清洗"必须发生在写入前的最后一刻，中间任何一次await都可能让 URL 又变了（比如路由刚跳转完）。finally里统一挂定时器，避免错误分支忘记重置导致按钮永久禁用。
resetDelay我默认给 1800ms，这个数字不是拍脑袋的。实测下来 1200ms 太短，用户视线还没扫到"已复制"就变回去了；3000ms 又太长，连续复制两次时会觉得按钮"卡住了"。1800ms 左右是大部分人能自然读到文案又不会烦躁的区间。
2.2 主路径：navigator.clipboard 的正确调用姿势
写剪贴板的入口函数把能力探测、主路径、降级三件事串起来：
// utils/clipboard.js function isSecure() { return typeof window !== 'undefined' && window.isSecureContext } export async function writeClipboard(text) { if (!text) { throw new Error('EMPTY_PAYLOAD') } if (navigator.clipboard?.writeText && isSecure()) { try { await navigator.clipboard.writeText(text) return } catch (e) { // 用户拒绝授权、页面失焦、iframe 未授权等情况都落到这里 // 统一走降级再试一次，代价极低 console.warn('[clipboard] writeText failed, fallback:', e?.name) } } legacyCopy(text) }这段代码看着简单，但每一行都有来历。
isSecure()的判断不能省。navigator.clipboard在不安全上下文（http://的局域网地址、file://打开的页面）里压根不存在，直接调会抛TypeError: Cannot read properties of undefined。而很多内部工具就是部署在http://192.168.x.x:8080上的，本地调试也经常用file://打开静态页，这个坑必踩。
async之后调写剪贴板，有个隐蔽的限制：用户激活窗口期。浏览器要求写剪贴板发生在用户的点击、触摸等激活事件的同步调用栈里，或者至少是极短的异步窗口内。如果你在copy()里先await fetch('/api/share/token')再写剪贴板，大概率会被拒，错误名是NotAllowedError，描述里经常带一句 "Document is not focused"。解决办法有两个：要么把地址算好放在点击前（推荐，地址本来就是本地能算出来的），要么用ClipboardItem塞一个 Promise 进去，让浏览器自己去等——后者兼容性不如前者，我通常不用。
还有一个容易忽略的前提：页面必须处于焦点状态。开发时打开 DevTools 点了断点，回来点按钮发现失败了，八成是断点期间文档失焦。线上场景里，如果页面嵌在一层 iframe 里，外层没给allow="clipboard-write"的权限策略，也会失败。这类问题没法在代码里根治，只能在错误处理里给一句人话提示。
2.3 降级路径：execCommand 的老办法怎么用得不难看
execCommand('copy')这套东西虽然废弃了，但它是目前唯一能在老环境和部分内嵌浏览器里工作的方案，该写还是得写。难点全在细节上：
// utils/clipboard.js function legacyCopy(text) { const textarea = document.createElement('textarea') textarea.value = text textarea.setAttribute('readonly', '') // 避免移动端弹出键盘 textarea.style.position = 'fixed' // 必须脱离文档流但仍在渲染树里 textarea.style.top = '0' textarea.style.left = '0' textarea.style.width = '1px' textarea.style.height = '1px' textarea.style.padding = '0' textarea.style.border = 'none' textarea.style.outline = 'none' textarea.style.boxShadow = 'none' textarea.style.background = 'transparent' textarea.style.opacity = '0' // 不能用 display:none / visibility:hidden textarea.style.pointerEvents = 'none' textarea.style.zIndex = '-1' document.body.appendChild(textarea) // 记录当前焦点和选区，复制完要还回去 const activeEl = document.activeElement const selection = document.getSelection() const savedRange = selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : null textarea.focus({ preventScroll: true }) textarea.select() textarea.setSelectionRange(0, textarea.value.length) let ok = false try { ok = document.execCommand('copy') } catch (e) { ok = false } document.body.removeChild(textarea) // 还原选区，否则用户输入框里的光标会丢失 if (savedRange && selection) { selection.removeAllRanges() selection.addRange(savedRange) } if (activeEl && typeof activeEl.focus === 'function') { activeEl.focus({ preventScroll: true }) } if (!ok) { throw new Error('LEGACY_COPY_FAILED') } }这里有几个点必须解释清楚，不然改的时候容易改坏。
为什么不能用display: none或visibility: hidden。这两个样式会让元素不参与渲染，select()拿不到有效的选区，execCommand直接返回false。正确的做法是让元素可见但不可感知：固定定位到左上角、1px 见方、透明、禁用指针事件、z-index压到最底。视觉上看不见，但布局和渲染树里有它。
为什么要readonly。移动端键盘的弹出条件之一是输入框获得焦点且可编辑，虽然这个 textarea 的尺寸是 1px，但某些机型上照样会闪一下键盘。加个readonly就彻底安静了。
为什么必须还原焦点和选区。这是我最开始漏掉的一步。假设用户在搜索框里打了半截字，输了一半光标在中间，点了"复制链接"，复制成功了，但焦点跑到了那个被删掉的 textarea 上，光标丢失，继续打字全跑到输入框末尾。用户不会觉得是复制按钮的问题，他会觉得输入框有 bug。这一行还原代码，是整个降级函数里性价比最高的部分。
为什么textarea.focus()要加preventScroll。不加的话，在某些布局下页面会跳到顶部，用户体验上是"点了复制，页面刷了一下"。
降级路径还有一个不能忽略的点：execCommand在部分结构里（比如按钮本身在一个contenteditable区域内，或者外层有复杂的 shadow DOM）会失败。我的做法是给一个非常明确的自定义错误，让上层能区分"降级失败"和"主路径失败"，方便埋点统计。
3. 安全过滤：能复制的地址不等于该复制的地址
3.1 哪些参数绝对不能出现在分享链接里
我第一次做这个功能时，想的是"复制地址就是复制用户看到的地址，有什么问题"。直到某次联调，同事把一个带?token=eyJhbGciOi...的详情页链接复制到了群里。虽然那个 token 有效期只有两小时，但这说明一个道理：浏览器地址栏里的 URL 是各种信息的混合体，包含页面状态、埋点参数、追踪标识，也经常包含身份凭证。
我的分类方法是这样：
| 参数类型 | 典型键名 | 处理策略 |
|---|---|---|
| 身份凭证 | token、access_token、auth、sessionId、sid、ticket | 一律剔除，不做例外 |
| 签名与防篡改 | sign、signature、nonce、timestamp | 剔除，重新生成后再分享 |
| 分享者私密信息 | userId、uid、phone、email | 默认剔除，除非业务明确要求 |
| 追踪与埋点 | utm_*、from、spm、ref | 视场景，外部分享一般保留from便于归因 |
| 混淆后仍敏感 | key、secret、pwd、password、code | 剔除 |
这张表不是拍脑袋来的，是按"这个参数泄露出去会被用来做什么"倒推的。凭证泄露可以直接冒充身份；签名泄露能被重放到其他接口；手机号邮箱泄露属于隐私事故。至于埋点参数，它泄露的只是"这个人从哪个入口进来"，风险等级完全不同。
需要提醒的是，黑名单永远覆盖不全。业务方加一个新参数叫_tk或者skey，你的正则匹配不到，照样漏。所以我倾向于加一层白名单兜底：维护一份"允许出现在分享链接里的参数名清单"，不在清单里的一律删掉。这在成熟一点的系统里更靠谱，缺点是新参数上线时要同步更新清单，需要流程配合。
3.2 用 URL 对象重建而不是正则替换
刚写的时候我用字符串正则删参数：href.replace(/[?&]token=[^&]*/g, '')。这么干了两次就发现一堆问题：删完可能留下?&或者末尾的?；参数值里有编码过的&时会误伤；hash 里的参数根本匹配不到；?a=1&token=x&b=2删掉中间那段之后两个&连着，虽然浏览器能解析，但贴出去不好看。
后来改成用URL对象整体解析再重建，代码短了，正确性也上来了：
// utils/shareUrl.js const SENSITIVE_PATTERNS = [ /^token$/i, /^access_?token$/i, /^auth$/i, /^session_?id$/i, /^sid$/i, /^ticket$/i, /^sign(ature)?$/i, /^nonce$/i, /^password$/i, /^pwd$/i, /secret/i, /(^|_)key$/i, ] export function isSensitiveKey(key) { return SENSITIVE_PATTERNS.some((re) => re.test(key)) } export function sanitizeUrl(rawUrl, options = {}) { const { allowKeys = [], // 白名单，优先级最高 dropHash = false, // 是否丢弃 hash keepOrigin = null, // 替换域名，见 6.1 } = options const base = typeof window !== 'undefined' ? window.location.origin : 'http://localhost' let url try { url = new URL(rawUrl, base) } catch { return '' } const allow = new Set(allowKeys.map((k) => k.toLowerCase())) // 关键：先收集再删除，边遍历边删会跳过元素 const toDelete = [] url.searchParams.forEach((_value, key) => { const lower = key.toLowerCase() if (allow.has(lower)) return if (isSensitiveKey(key)) toDelete.push(key) }) toDelete.forEach((key) => url.searchParams.delete(key)) if (dropHash) { url.hash = '' } else if (url.hash.includes('?')) { url.hash = sanitizeHashFragment(url.hash, { allowKeys, allow }) } if (keepOrigin) { const replaced = new URL(keepOrigin) url.protocol = replaced.protocol url.host = replaced.host } // URL#toString 会给根路径补一个 '/'，末尾孤零零的 '?' 也一并清掉 return url.toString().replace(/\?$/, '') }searchParams.forEach这一行是重中之重。我第一版是直接在里面url.searchParams.delete(key)，写完自测通过了，因为测试用的 URL 里只有一个敏感参数。上线之后遇到?token=a&sign=b这种两个敏感参数挨在一起的，只删掉了第一个——原因是URLSearchParams是活的对象，遍历过程中删除当前项会导致后一个被跳过。改成"先收集键名、再统一删除"就彻底解决了。这种 bug 单元测试不写全就发现不了，而真实业务里两个敏感参数相邻的情况太常见了。
new URL(rawUrl, base)传第二个参数也有讲究。传了 base，相对路径和//开头的协议相对路径都能正确解析；不传的话遇到相对路径直接抛异常。SSR 环境下window不存在，所以给了一个兜底 base。
3.3 hash 路由、多重编码与边界情况
hash 路由的项目里，真实的查询参数藏在#后面，url.searchParams根本够不着。比如https://example.com/#/order/detail?id=88&token=abc，url.search是空的，url.hash是#/order/detail?id=88&token=abc。这时候得单独解析 hash：
function sanitizeHashFragment(hash, { allowKeys, allow }) { const raw = hash.replace(/^#/, '') const qIndex = raw.indexOf('?') if (qIndex === -1) return hash const path = raw.slice(0, qIndex) const query = raw.slice(qIndex + 1) const params = new URLSearchParams(query) const toDelete = [] params.forEach((_v, key) => { const lower = key.toLowerCase() if (allow.has(lower)) return if (isSensitiveKey(key)) toDelete.push(key) }) toDelete.forEach((key) => params.delete(key)) const nextQuery = params.toString() return `#${path}${nextQuery ? `?${nextQuery}` : ''}` }这里有个细节值得单说：URLSearchParams#toString()会对键值重新编码，空格会变成+，中文会变成百分号编码。如果你的原链接里参数是已经编码过两次的（比如后端生成链接时多 encode 了一次），重新序列化之后可能反而"解码"了。我的处理原则是：清洗后一律以URL对象的输出为准，不再尝试保留原始编码形态。理由很简单，重新序列化后的结果一定是合法的 URL，而保留原样反而可能带出编码不一致的问题。
中文参数是另一个高频场景。假设链接是#/search?kw=设计稿，浏览器地址栏会显示成%E8%AE%BE%E8%AE%A1%E7%A8%BF。复制的时候要不要解码成中文？我的结论是不要。一旦解码，重新贴进地址栏时如果对方浏览器或聊天软件的自动识别逻辑有差异，可能把中文字符当成分隔符截断。保持编码状态虽然难读，但绝不会出错。
还有一个边界：超长 URL。某些 IM 在识别链接时会截断超过一定长度的文本，用户复制了但对面点开是半截。这个没法在剪贴板层面解决，只能在产品层面提示"链接较长，建议用短链分享"。我在代码里加了一个长度检查，超过 800 字符时打一条警告日志，方便排查。
4. 交互反馈与可访问性细节
4.1 四种状态的视觉与文案
状态机有了，落到界面上得给每个状态一个明确的表达。我用的方案是><template> <button type="button" class="copy-btn" :data-state="status" :disabled="status === 'copying'" @click="handleCopy" > {{ buttonLabel }} </button> <span class="sr-only" aria-live="polite">{{ liveText }}</span> </template> <script setup> import { computed } from 'vue' import { useClipboard } from '@/composables/useClipboard' import { sanitizeUrl } from '@/utils/shareUrl' const { status, copy } = useClipboard({ resetDelay: 1800 }) const LABELS = { idle: '复制链接', copying: '复制中', success: '已复制', error: '复制失败', } const buttonLabel = computed(() => LABELS[status.value] ?? '复制链接') const liveText = computed(() => status.value === 'success' ? '链接已复制到剪贴板' : status.value === 'error' ? '复制失败，请手动选中地址栏复制' : '' ) async function handleCopy() { const url = sanitizeUrl(window.location.href, { allowKeys: ['from'] }) await copy(url) } </script>
handleCopy里有一点必须注意：sanitizeUrl是同步的，紧接着调copy，整个过程在点击事件的同一个任务里发起。这是保证"用户激活"有效的关键。如果你在中间插一个await nextTick()或者await fetch()，在部分浏览器上就会被判定为异步调用而拒绝。
disabled只在copying状态加，success和error状态不加。原因在于用户可能连续点两次（第一次没看清），禁用会让他觉得按钮坏了。至于copying状态通常只有几毫秒，实际几乎看不到，加上只是为了极端情况下防止重复触发。
4.2 屏幕阅读器与键盘用户
这个功能最容易被忽略的是可访问性。用鼠标点的用户看到文案变化就知道成功了，屏幕阅读器用户什么都感知不到——按钮文字变了不会触发朗读，除非你用了aria-live。
所以模板里那个.sr-only的span是必要的，不是装饰。它的内容在状态变化时更新，屏幕阅读器会自动播报。用aria-live="polite"而不是assertive，是因为复制成功不是紧急信息，打断用户当前朗读反而不礼貌。
.sr-only的标准写法：
.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }另外键盘用户这块，<button>元素天然支持 Enter 和 Space 触发，前提是不要用<div @click>去模拟按钮。我见过为了样式灵活用 div 的，结果键盘完全用不了。样式问题用 CSS 解决，语义问题不要动 HTML。
4.3 内嵌浏览器与移动端的差异
这块是我踩坑最多的地方，因为内部工具的流量有相当一部分来自各种 App 的内置 WebView，情况比标准浏览器复杂得多。
部分内嵌浏览器的 Clipboard API 是残缺的。有些环境里navigator.clipboard对象存在，writeText方法也在，但调用之后返回的 Promise 既不 resolve 也不 reject，就那么挂着。表现是按钮永远停在"复制中"。我一开始没有给超时，用户反馈"点了没反应"。后来加了一层超时保护：
function withTimeout(promise, ms) { return new Promise((resolve, reject) => { const timer = setTimeout(() => reject(new Error('CLIPBOARD_TIMEOUT')), ms) promise.then( (v) => { clearTimeout(timer); resolve(v) }, (e) => { clearTimeout(timer); reject(e) } ) }) }调用改成await withTimeout(navigator.clipboard.writeText(text), 1500)。超时之后就落到降级路径，降级通常能成功。这个 1500ms 的选择也有讲究：正常写剪贴板是毫秒级的，超过 1 秒基本可以判定为环境问题。给太短会误伤低端设备，给太长用户已经以为卡死了。
iOS 上的选区还原更敏感。前面提到的activeElement.focus()还原，在 iOS 上如果元素是输入框，可能会重新弹出键盘。加preventScroll能缓解，但如果复制按钮本身就在一个表单页面里，用户点完复制结果键盘弹起来了，体验依然很差。我的处理是：在移动端判断当前焦点元素是否是可编辑控件，如果不是就不还原焦点，只还原选区。
不同设备对"用户激活"的判定窗口不同。桌面端相对宽松，移动端严格得多，某些机型上即使在同一个点击回调里，只要中间隔了一个 microtask 就失败。所以我把清洗 URL 的逻辑写成同步函数，坚决不用async，就是为了减少微任务层数。
5. 常见问题排查实录
5.1 问题速查表
下面这张表是我在项目里整理出来的，遇到问题先对着看，能省掉大量瞎猜的时间：
| 现象 | 大概率原因 | 排查动作 | 处理方式 |
|---|---|---|---|
| 按钮点了没任何反应 | navigator.clipboard为undefined | 控制台看window.isSecureContext | 检查是否为 http 或 file 协议，走降级 |
| 一直停在"复制中" | 写剪贴板 Promise 挂起 | 加日志看是否进入 then | 加超时保护，超时走降级 |
报NotAllowedError | 页面失焦或用户拒绝授权 | 查document.hasFocus() | 提示用户点击页面后重试 |
| 复制出来的链接少了参数 | 过滤规则误伤 | 打印过滤前后的 URL 对比 | 把参数名加进白名单 |
| 复制出来中文变乱码 | 二次编码或强制解码 | 对比location.href与复制结果 | 保持编码状态，不做解码 |
| 复制后输入框光标跳走 | 未还原焦点和选区 | 检查legacyCopy的还原段 | 补上activeElement.focus() |
| 分享了打不开 | 复制到了本地或内网域名 | 看 URL 的 host | 域名映射或直接给生产地址 |
| iframe 里复制失败 | 权限策略未授权 | 看控制台是否有 policy 报错 | 外层容器加剪贴板权限声明 |
表格里最后两行值得单独展开说说，因为它们的排查成本比前面几行高得多。
"分享了打不开"这个问题第一次出现时，我排查了半小时才反应过来：复制的链接是http://localhost:5173/order/88。开发同学在自己机器上点复制，发给产品，产品当然打不开。这个问题在开发阶段几乎每个新人都会遇到一次。解决思路有两个方向：一是在开发环境把域名替换成固定的测试环境地址；二是直接在开发环境禁用这个按钮，或者在复制的内容里加一行说明。我选了第一种，因为团队里经常需要互相分享本地页面，有个可访问的测试环境地址反而方便。
"iframe 里复制失败"更隐蔽。我们的工具被嵌在某个后台系统里，外层容器没给剪贴板权限，navigator.clipboard.writeText直接抛NotAllowedError，而execCommand在跨域 iframe 里同样可能失败。这种情况下唯一的出路是让外层容器在<iframe>上声明剪贴板写入权限，或者退回"手动选中复制"的提示。我加了一个检测：
function isInIframe() { try { return window.self !== window.top } catch { return true // 跨域时访问 top 会抛异常，说明在 iframe 里 } }检测到在 iframe 里、且两条路径都失败时，把文案改成"当前环境不支持一键复制，请手动选中地址栏复制"，至少给用户一条明确的出路，而不是让他反复点击猜测。
5.2 三个印象最深的现场
现场一：成功状态被误报。有个用户反馈"显示已复制，但粘贴出来是空的"。查了半天发现，那个环境里execCommand('copy')返回了true，但实际什么都没写进去——某些魔改过的 WebView 里execCommand的返回值不可信。理论上可以用navigator.clipboard.readText()回读校验，但读剪贴板需要额外权限，弹窗打断感很强，得不偿失。我的处理是在返回true之后仍然提示"已复制"，同时埋一个点，如果同一用户短时间内反复点击同一个按钮超过三次，就判定为失败场景，自动降级到手动提示。这个启发式规则不完美，但比什么都不做好。
现场二：清洗规则误杀业务参数。我们有个页面的查询参数叫sharekey，是分享来源的标识，不敏感。但我的黑名单里有一条/(^|_)key$/i，正好匹配上了，导致这个参数被删掉，分享归因全丢。这个 bug 上线三天才被发现，因为归因数据是异步统计的，短期看不出异常。教训是：黑名单上线前一定要跑一遍全站 URL 参数清单，把所有出现过的参数名列出来逐个过一遍，不要凭印象写规则。
现场三：定时器没清导致的诡异状态。用户快速连续点击两次复制按钮，第二次点击时上一次的reset定时器还在跑，1.8 秒后把状态重置成idle，而此时第二次复制其实刚成功，按钮上的"已复制"提前消失了。修复很简单，在copy开头就clearTimer()，我在 2.1 的代码里已经加上了。这种 bug 复现概率低，但用户一旦遇到就会觉得"这东西时灵时不灵"，对功能可信度伤害很大。
6. 还能往下做的几个方向
6.1 域名映射与短链兜底
前面提到开发环境的链接分享出去打不开。一个比较稳妥的做法是维护一张环境域名映射表，复制时把本地或测试域名换成对应的可访问地址：
const HOST_MAP = { 'localhost': 'https://demo.example-internal.test', '127.0.0.1': 'https://demo.example-internal.test', } function normalizeHost(url, map = HOST_MAP) { const target = map[url.hostname] if (!target) return url const next = new URL(target) url.protocol = next.protocol url.host = next.host return url }这段代码要小心一件事：域名换了之后，原本依赖 cookie 的会话可能失效，对方打开会跳到登录页。所以这个能力最好只在明确的"分享"场景启用，而不是所有复制场景都开，否则用户复制自己的链接去另一个标签页打开，发现要重新登录，体验很差。
如果链接确实很长，或者需要埋分享渠道，还可以接一层短链服务。但短链引入的复杂度不小——需要后端接口、需要处理生成失败、需要防止短链被滥用。我的判断是，除非有明确的运营需求，否则别上。复制地址这个功能本身应该保持"零依赖"，一旦它依赖网络请求，就会遇到前面说的"用户激活丢失"问题，反而让核心功能变脆。
6.2 复制内容的多样化
现在这套封装只处理纯文本。如果业务需要复制带格式的内容（比如同时写入text/html和text/plain），navigator.clipboard.write配合ClipboardItem是更合适的入口。写法上要注意，ClipboardItem的构造参数是一个对象，键是 MIME 类型，值是 Blob 或字符串 Promise：
async function writeRichText({ plain, html }) { if (!navigator.clipboard?.write || !window.ClipboardItem) { return writeClipboard(plain) // 不支持富文本就退回纯文本 } const item = new ClipboardItem({ 'text/plain': new Blob([plain], { type: 'text/plain' }), 'text/html': new Blob([html], { type: 'text/html' }), }) await navigator.clipboard.write([item]) }这个能力的浏览器支持情况参差，尤其是老版本的 WebView，所以一定要有纯文本兜底。我在实际项目里只在明确需要"粘贴到富文本编辑器还保留格式"的场景才用它，普通链接复制走纯文本路径，简单可靠。
至于整个功能的扩展边界，我的原则是别把它做成平台。它就是一个几十行的工具函数加一个按钮，能正确复制、能正确过滤、能在异常时给人话提示，任务就完成了。真要再往上加东西，比如复制历史记录、复制统计看板，那是另外一回事，不该长在这个 composable 上。我见过一个复制功能被加了七个参数、支持五种内容类型、内部维护三个缓存，最后改一行文案要读半小时代码——那种复杂度，不值得。
