migrate

Lodash 迁移与兼容指南

指导用户将 lodash 迁移到 es-toolkit，并基于实际源代码了解严格 API 与兼容 API 的区别。

输入

$ARGUMENTS — 要迁移的 Lodash 代码、具体函数名称，或关于严格 API 与兼容 API 的问题。

核心概念

es-toolkit（严格 API）：面向 85% 常见用例的精简、简化 API。打包体积更小，但在边缘情况下可能会有意与 lodash 不同。新函数会添加到此处。

es-toolkit/compat：旨在在指定范围内完全兼容 lodash 测试。范围之外的行为（例如隐式类型转换、原型修改），请参阅 docs/compatibility.md。

为什么要优先查看源代码

要了解严格 API 与兼容 API 的区别，唯一可靠的方法是检查用户项目中安装的版本。此技能可能作为独立目录安装，因此切勿假设 es-toolkit 仓库或同级的 docs 目录可用。

工作流

如果提供了具体函数或 lodash 代码

1. 从输入中识别 lodash 函数

提取所用的 lodash 函数及其导入方式。

2. 验证已安装的包中是否提供这些函数

在依赖 es-toolkit 的包中运行。在 monorepo 中，这通常是工作区包，而不是仓库根目录。如果项目使用 Yarn Plug'n'Play，请使用 yarn node，而不是 node。

将示例名称替换为输入中找到的 lodash 函数：

node --input-type=module -e "
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const names = ['get', 'chunk', 'map'];
const pkg = require('es-toolkit/package.json');
const entries = Object.keys(pkg.exports)
  .filter(subpath => subpath !== './package.json' && !subpath.includes('*'))
  .map(subpath => subpath === '.' ? 'es-toolkit' : 'es-toolkit/' + subpath.slice(2));
const modules = await Promise.all(entries.map(entry => import(entry).catch(() => null)));
if (modules.every(module => module == null)) {
  console.error('es-toolkit is not resolvable from ' + process.cwd());
  process.exit(1);
}
for (const name of names) {
  const found = entries.filter((_, index) => modules[index] != null && name in modules[index]);
  console.log(name.padEnd(20), found.join(', ') || 'NOT AVAILABLE');
}
"

函数可能出现在多个入口点中，因此请阅读完整结果。es-toolkit/types 仅包含类型，无法通过运行时导入进行检查。

使用以下命令解析包元数据，然后阅读其 dist/ 目录下的声明文件，以获取准确的签名和 JSDoc。不要假设包位于常规的 node_modules 路径下。

node -e "console.log(require.resolve('es-toolkit/package.json'))"

如果当前项目本身就是 es-toolkit 源代码仓库，请直接检查 src/{category}/{fn}.ts、src/compat/{category}/{fn}.ts 及其规格文件，而不是要求使用已构建的包。

3. 确定合适的迁移路径

场景	建议
函数在两者中都存在，且行为相同	使用 es-toolkit（打包体积更小）
函数在两者中都存在，但行为不同	说明差异，由用户选择
仅在 compat 中存在	使用 es-toolkit/compat
均不可用	保留 lodash，或建议使用现代 JavaScript 替代方案

如果函数仅在 compat 中存在（例如 get、set、has），请说明原因——es-toolkit 不实现可由现代 JavaScript 替代的函数（如可选链 ?.、Object.hasOwn() 等）。

4. 生成迁移前后对比

对于每个函数，请提供：

• 可用性：es-toolkit 和/或 es-toolkit/compat
• 文档链接：https://es-toolkit.dev/reference/{category}/{fn}.html（严格版）或 https://es-toolkit.dev/compat/reference/{category}/{fn}.html（兼容版）
• 迁移前（lodash）和迁移后（es-toolkit）的代码示例
• 从源代码中发现的任何行为差异
• 功能对比表：并排比较 API 功能（例如取消支持、flush、maxWait、返回值、AbortSignal、回调参数）。阅读两者的实现，找出所有支持的选项，并以如下表格呈现：

功能	lodash	es-toolkit	es-toolkit/compat
（逐项列出选项/功能）	✅/❌	✅/❌	✅/❌

• “何时使用哪种方案”：根据功能对比，提供基于场景的建议，例如：“如果只需要基本的 debounce，请使用 es-toolkit；如果依赖 cancel/flush，请使用 compat；如果需要 X，请继续使用 lodash。”

涉及许多函数的迁移，请使用汇总表，而不是为每个函数重复完整模板。

5. 提供汇总的导入改写

使用单个代码块展示最终的导入转换。

5a. 为大规模迁移建议自动化方案

迁移多个文件时，请提及实用的自动化方案：

• 打包器别名：在 webpack 或 Vite 中配置 resolve.alias，在构建时重定向 lodash 导入，无需更改源文件：

  // vite.config.js or webpack.config.js
  resolve: { alias: { 'lodash': 'es-toolkit/compat' } }
  

• ESLint 规则：使用 no-restricted-imports，在迁移后对仍存在的 lodash 导入发出警告或报错。
• Codemod：如果迁移模式较复杂，请提及 jscodeshift 等用于基于 AST 进行系统性转换的工具。

6. 说明对打包体积的影响

说明严格版和兼容版的导入都支持 tree-shaking，但只有在测量用户的项目或查阅 es-toolkit 源代码检出中的最新基准数据后，才能引用精确的体积或性能数据。否则，请链接到官方的打包体积和性能页面。

如果未指定具体函数（迁移策略概览）

提供包含以下三种迁移方案的策略概览：

• 方案 A：直接迁移到 es-toolkit — 新项目或小型项目
• 方案 B：逐步通过 compat 迁移 — 大型代码库（建议用于遗留项目）
• 方案 C：混合迁移 — 务实方案

每种方案都要包含权衡矩阵：

因素	方案 A（严格版）	方案 B（兼容版）	方案 C（混合）
代码改动量	高	低	中
打包体积缩减	最大	中等	不定
风险等级	较高（行为差异）	低（兼容 lodash）	中
维护成本	低（API 简洁）	中（跟踪兼容性）	较高（两套 API）

仅 compat 提供的函数：搜索 src/compat/ 中不存在于严格版 src/ 的函数。列出一些代表性示例，让用户了解哪些函数只能通过 compat 使用（例如 get、set、has）。

对于具体的行为差异，请阅读一些具有代表性的函数实现（例如 chunk、debounce），提供实际示例，而不是抽象描述。

文档链接

• 迁移概览：https://es-toolkit.dev/compat/intro.html
• 打包体积：https://es-toolkit.dev/bundle-size.html
• 性能：https://es-toolkit.dev/performance.html

函数页面使用以下格式：

• 严格版：https://es-toolkit.dev/reference/{category}/{fn}.html
• 兼容版：https://es-toolkit.dev/compat/reference/{category}/{fn}.html
• fp：https://es-toolkit.dev/fp/reference/{fn}.html

如果不确定页面是否存在，请省略页面链接，不要猜测。