一键告别 polyfill：temporal-polyfill-codemod 迁移到原生 Temporal 的完整教程

一键告别 polyfilltemporal-polyfill-codemod 迁移到原生 Temporal 的完整教程【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporaltemporal-polyfill 是继任 JavaScript Date 对象的轻量级 Temporal polyfill而 temporal-polyfill-codemod 正是当原生 Temporal 全面落地时帮你一键把旧代码迁移到原生 Temporal 的自动化迁移工具。本文将从安装运行、参数详解到 CI 集成给你一份完整的 temporal-polyfill 迁移教程让告别 polyfill这件事变得简单、快速、零风险。为什么现在要考虑告别 polyfillTemporal 作为 JavaScriptDate对象的官方继任者正在逐步进入主流浏览器与运行时。而temporal-polyfill存在的意义是在原生 Temporal 尚未普及的过渡期提供一份不到 20 kB、完全符合规范的兼容实现。但过渡期总会结束。当你的目标环境已经原生支持 Temporal 时继续背着 polyfill 反而会增加包体积、拖慢加载。此时最理想的状态是代码迁移到原生Temporal.*polyfill 依赖被彻底删除。这正是temporal-polyfill-codemod诞生的原因——它把这种理想变成一条命令。fns API 与原生 Temporal 到底差在哪temporal-polyfill除了提供全局Temporal之外还附带一套tree-shakeable 函数 API位于temporal-polyfill/fns下每个操作都是一个独立函数作用于普通 record 对象好处是打包时只保留用到的部分import * as PlainDateFns from temporal-polyfill/fns/PlainDate const date PlainDateFns.create(2026, 6, 1) const later PlainDateFns.addMonths(date, 2)而原生 Temporal 则是标准的类与实例方法风格。两种写法在运行时完全不相容fns 操作的是普通对象原生 Temporal 操作的是真正的Temporal实例。这意味着迁移不能靠搜索替换糊弄过去必须精确地逐行改写——这正是 codemod 擅长的机械工作。temporal-polyfill-codemod 一键迁移命令工具的使用方式极其简单通过npx即可直接运行无需安装npx temporal-polyfill-codemod fns-to-temporal pathpath可以是一个文件也可以是一个目录目录会被递归扫描自动跳过node_modules、dist和点开头的隐藏目录。支持js, jsx, ts, tsx, mjs, cjs, mts, cts全部常见扩展名覆盖绝大多数前端与 Node 项目。上面代码中的path换成你的src目录即可。如果你需要基于本仓库源码研究或二次开发也可以先克隆完整仓库git clone https://gitcode.com/gh_mirrors/tempo/temporal迁移前后的代码长什么样以最常见的日期操作为例迁移前使用temporal-polyfill/fns命名空间import * as PlainDateFns from temporal-polyfill/fns/PlainDate const date PlainDateFns.create(2024, 5, 1) const next PlainDateFns.addDays(date, 3)运行 codemod 之后自动变成标准的原生 Temporal 写法const date new Temporal.PlainDate(2024, 5, 1) const next date.add({ days: 3 })可以看到构造函数、实例方法、静态方法都被精准映射——create变成new Temporal.PlainDate(...)addDays变成date.add({ days: 3 })compare变成Temporal.PlainDate.compare(a, b)。它还能自动处理哪些迁移场景除了最常见的构造函数与方法调用temporal-polyfill-codemod还覆盖了 3 类容易踩坑的隐藏场景1. 日历 record 自动转为日历 ID。在需要日历参数的位置如PlainDateFns.create(2024, 5, 1, CalendarFns.getBuddhist())会直接改写为new Temporal.PlainDate(2024, 5, 1, buddhist)。2. 类型声明同步改写。代码中的 record 类型与选项类型会映射到 Temporal 等价类型例如PlainDateRecord变成Temporal.PlainDate、CalendarRecord变成string让 TypeScript 类型一路畅通。3. 类型守卫自动升级。PlainDateFns.isRecord(value)会改写为更地道的value instanceof Temporal.PlainDate语义完全一致。这些规则的全部映射矩阵都记录在转换契约文档中感兴趣可以查看 codemod/ARCHITECTURE.md以及核心转换源码 codemod/src/index.ts。--dry 预演模式迁移前先预览全部改动把代码一次性交给工具改写多少有点不放心temporal-polyfill-codemod提供了最稳妥的预演模式temporal-polyfill-codemod fns-to-temporal path --dry --print--dry表示只计算、不写文件--print则把每个被修改文件的新内容打印到终端。两者组合你可以在不触碰任何文件的情况下逐行审查迁移结果确认无误后再正式执行。这是把迁移风险降到最低的关键一步强烈建议纳入流程。temporal-polyfill-codemod 无法迁移的 3 种情况工具设计得刻意保守只有语法上能明确推导出 Temporal 等价表达式的代码才会被改写。遇到以下情况它会保留原样并输出诊断信息函数引用被当作值传递例如const fn PlainDateFns.addDays之后再用变量调用动态/计算属性访问例如PlainDateFnsname命名空间被解构以及roundTo*调用中选项与隐含单位冲突等边缘场景。这些诊断默认是迁移阻塞性的运行结束后工具会打印所有问题并以退出码1结束方便接入 CI——只要还有未迁移的 fns 代码流水线就会失败绝不会出现半迁移的代码悄悄上线。CI 集成与 --allow-warnings 的正确用法把 codemod 放进 CI 是保证彻底告别 polyfill的最有效手段temporal-polyfill-codemod fns-to-temporal src/默认情况下只要有任何残留的 fns 用法命令就返回非零退出码构建即失败。对于想在本地先看看部分结果、不阻塞流程的场景可以加上--allow-warnings它只会改变退出码诊断信息依旧完整打印。工具也会在需要时提示你安装temporal-utils某些 fns helper 在原生 Temporal 中没有直接对应物例如startOfMonth、diffDays这类常用便捷操作会改写为temporal-utils的等价函数——这正是一套互补的日常工具库详情见 utils/README.md。TypeScript 项目的 3 个注意事项如果你的项目是 TypeScript 写的迁移后还有 3 件事值得留意类型会被改写为全局Temporal类型但 codemod 不会替你注入类型声明需要项目自行提供例如通过temporal-spec或环境自带的类型。如果迁移引入了temporal-utils的导入记得在对应包中安装该依赖工具不会替你修改package.json。如果新导入的符号与本地变量重名工具会自动做别名处理一般无需担心冲突。完整 CLI 的参数与帮助文本可以在 codemod/src/cli.ts 中查看CLI 入口封装在 codemod/package.json 的bin字段里。完整的 6 步迁移工作流把上面所有内容串起来一次稳妥的迁移只需要 6 步预演npx temporal-polyfill-codemod fns-to-temporal src/ --dry --print审查全部改动执行去掉--dry正式运行让工具批量改写收尾按工具提示安装temporal-utils如有需要并运行你自己的格式化工具处理残留根据诊断信息手工修复无法自动迁移的少数代码再次运行直到输出干净验证跑一遍测试套件确认日期逻辑无回归移除依赖删除temporal-polyfill依赖让原生 Temporal 完全接管。至此你的项目就真正完成了从 polyfill 到原生 Temporal 的迁移——体积更小、性能更好、代码更标准。如果之前还不熟悉 polyfill 本身建议先阅读 polyfill/README.md 了解它的设计而今天这篇 temporal-polyfill-codemod 教程就是你踏上告别 polyfill之路的第一块跳板。【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考