structuredClone 类型怎么配置或排查

在 TypeScript 项目里写下 structuredClone(value) 后，如果编辑器提示“找不到名称 structuredClone”或“没有这个属性”，先不要把它当成浏览器不支持。多数时候，问题发生在编译器加载的声明文件：浏览器项目缺少 DOM，Node 项目缺少匹配的 Node 类型包，或者 noLib、types 把默认类型入口关掉了。类型补齐后，还要单独确认实际运行环境确实提供这个 API。

规范参考：https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone

先分清类型缺失和运行时缺失

structuredClone() 使用结构化克隆算法生成深拷贝，也能保留循环引用；它不是把对象转成 JSON 再解析。浏览器端的声明通常来自 TypeScript 的 DOM 库，Node.js 则从运行时全局对象和 Node 类型声明获得提示。

Node.js 官方全局对象文档标明，structuredClone 从 Node.js v17.0.0 加入。如果部署目标低于这个版本，单纯添加类型声明只会让编译器安静，不能凭空补出运行时实现。

用 tsconfig 分别配置浏览器和 Node.js

先运行项目原本使用的 TypeScript 版本，再打开最终生效的配置。不要只看根目录里的文件：Vite、Webpack、测试工具或 monorepo 可能通过 extends 叠加配置。浏览器项目的最小方向如下，target 可按兼容矩阵下调，但 DOM 仍要保留。

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "strict": true
  }
}

如果是 Node.js 服务，重点是让运行时版本、编译器版本和 @types/node 对齐。使用自定义 lib 时，不要把浏览器和服务端类型混成一套；服务端项目还应确认依赖树中确实安装了 Node 类型包。

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022"],
    "types": ["node"],
    "strict": true
  }
}

这里的关键不是把版本号改得越新越好，而是让声明与实际宿主一致。若项目设置了 noLib: true，TypeScript 会忽略自动库；若设置了 types，只有列出的全局类型包会进入全局作用域。修改后重启语言服务，并检查继承配置是否覆盖了当前文件。

最小示例能同时暴露类型和数据边界

配置完成后，用一个小对象确认返回值仍保持类型信息。下面的示例只演示类型关系和边界判断；注释中的断言不是生产代码的替代品。

type Draft = {
  title: string;
  tags: string[];
};

const source: Draft = { title: "前端草稿", tags: ["ts"] };
const copy = structuredClone(source); // 返回值会保留 Draft 的结构
copy.tags.push("clone"); // 深拷贝后的数组不会与 source.tags 共享引用

const cycle: { name: string; self?: unknown } = { name: "节点" };
cycle.self = cycle; // 结构化克隆可以处理循环引用
const cycleCopy = structuredClone(cycle);

try {
  structuredClone({ render: () => "不可克隆" }); // 函数成员会触发 DataCloneError
} catch (error) {
  console.error("输入包含不可结构化克隆的成员", error); // 生产代码应记录对象来源并返回可处理错误
}

这个示例把两类问题分开了：如果第一处调用就无法通过类型检查，回到 lib、types 和项目宿主；如果能编译但 try 中失败，则是输入值不满足结构化克隆规则。Date、Map、Set、数组缓冲区等常见值可以按 API 规则处理，但属性描述符、访问器语义和函数本身不能按原样复制。

最后做一次兼容性排查

把检查分成“声明、构建、运行”三层，效率最高。声明层确认编辑器不再报错；构建层确认实际使用的 tsconfig 没被脚本替换；运行层则根据浏览器版本或 Node.js 版本决定是否直接调用、提供 polyfill，或保留项目已有的兼容实现。

• 浏览器端：确认目标浏览器覆盖范围，并让构建工具真正处理旧浏览器策略；不要把 DOM 类型当作 polyfill。
• Node.js 端：Node.js v17.0.0 以前没有这个全局 API，升级运行时或在边界层使用经过评估的替代方案。
• 数据端：跨 Worker、持久化或传输 ArrayBuffer 时，核对是否使用了 transfer；被转移的缓冲区会从原对象脱离。

如果只想定位当前工程到底加载了什么，可以查看构建脚本指向的配置文件，再对照 TypeScript 官方 lib 说明。不要用 skipLibCheck 掩盖全局声明缺失，它主要影响声明文件检查，不会让运行时凭空出现 structuredClone。

常见问题

把 target 改成 ES2021 就一定能解决吗？

不一定。target 控制输出语法，API 类型主要由 lib 和宿主类型决定；运行时还要实际支持这个全局方法。

浏览器项目为什么会提示 structuredClone 不存在？

常见原因是自定义 lib 时删掉了 DOM，或工程使用了不包含 DOM 声明的共享基础配置。先检查最终合并后的 tsconfig。

structuredClone 能替代 JSON.parse(JSON.stringify()) 吗？

它能处理循环引用和更多内置类型，但不是万能序列化器；函数、DOM 节点以及业务对象中的不可克隆成员仍会失败。

加上 declare function 能不能永久修好？

只能暂时绕过编辑器提示，不能补运行时实现，还可能掩盖宿主版本不匹配。优先修正 lib、Node 类型包和部署版本。

排查这类问题时，最稳的顺序是先确认“代码跑在哪里”，再确认“TypeScript 看到了哪些声明”，最后检查“传入的值能否被结构化克隆”。按这三层处理，通常不用反复试错版本号。