Lodash-es

Lodash 的 ES Module 版本，支持 tree-shaking，是现代前端构建工具（Webpack、Vite、Rollup）中按需加载 Lodash 函数的推荐方式。

技术简介说明

Lodash-es 是 Lodash 工具库的 ES Module（ESM）版本，与主包 Lodash 共享完全相同的 API 和功能实现。它的核心区别在于模块系统：Lodash 使用 CommonJS（require/module.exports），而 Lodash-es 使用 ES Modules（import/export）。这一差异使得 Lodash-es 能够被现代打包工具进行静态分析和 tree-shaking，从而只打包项目中实际使用的函数，显著减少最终构建体积。

在现代前端工程化中，tree-shaking 是减小 JavaScript 打包体积的关键手段之一。使用 lodash-es 配合 Webpack 4+、Vite 或 Rollup，开发者可以通过 import { debounce } from 'lodash-es' 的方式按需导入，让打包工具自动移除未使用的代码。相比全量导入 Lodash（~71 KB gzip），lodash-es 的按需导入可以将相关代码体积减少 90% 以上。

2026 年，随着 es-toolkit 等现代替代品的崛起，lodash-es 仍然是存量项目中最常见的 tree-shaking 方案，同时也是向现代工具库过渡的桥梁。

基本信息

• 官网：https://lodash.com
• GitHub：https://github.com/lodash/lodash（与 Lodash 共享仓库）
• License：MIT
• 最新版本：v4.18.1（2026 年 4 月发布）
• 主要维护者：与 Lodash 相同（John-David Dalton、Ulises Gascón、OpenJS Foundation）
• npm 包名：lodash-es
• 模块格式：ES Modules（ESM）

快速上手

安装

# npm
npm install lodash-es
 
# yarn
yarn add lodash-es
 
# pnpm
pnpm add lodash-es

基础配置

Vite（默认支持，无需额外配置）：

// vite.config.js — 无需特殊配置，Vite 原生支持 ESM tree-shaking
import { defineConfig } from 'vite';
 
export default defineConfig({
  // 默认行为即可
});

Webpack 5（默认支持）：

// webpack.config.js — Webpack 5 默认启用 tree-shaking
module.exports = {
  mode: 'production', // tree-shaking 在生产模式下生效
  optimization: {
    usedExports: true, // 默认已启用
  },
};

Rollup：

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
 
export default {
  input: 'src/main.js',
  plugins: [resolve()],
  // Rollup 原生支持 ESM tree-shaking
};

TypeScript 配置：

npm install --save-dev @types/lodash-es

最小示例

// ✅ 按需导入（推荐，支持 tree-shaking）
import { debounce, cloneDeep, isEqual } from 'lodash-es';
 
const debouncedFn = debounce(() => {
  console.log('debounced!');
}, 300);
 
// ✅ 也可以导入单个方法
import debounce from 'lodash-es/debounce';

核心概念与架构

与 Lodash 的关系

Lodash-es 与 Lodash 共享同一套源代码，构建时通过不同的模块格式输出：

Tree-shaking 工作原理

Tree-shaking 依赖于 ES Module 的静态结构特性：

1. 静态分析：ESM 的 import/export 在编译时确定，打包工具可以静态分析依赖图
2. 标记未使用导出：打包工具标记所有未被引用的导出
3. 移除死代码：在压缩阶段移除未使用的导出代码

// 只使用了 debounce，其他函数会被 tree-shaking 移除
import { debounce, cloneDeep } from 'lodash-es';
 
// 最终打包产物只包含 debounce 相关代码

核心特性

• 原生 ESM 支持：使用标准 import/export 语法，与现代打包工具无缝集成
• Tree-shaking 友好：打包工具可自动移除未使用的函数，显著减小构建体积
• API 完全一致：与 Lodash 300+ 工具函数 API 完全相同，零学习成本
• 按需解构导入：支持 import { fn } from 'lodash-es' 的简洁语法
• 与 TypeScript 配合：通过 @types/lodash-es 提供完整类型支持
• 同步版本更新：与 Lodash 主包保持同步发布，安全性一致
• 多打包工具兼容：Webpack 4+、Vite、Rollup、esbuild 等均支持
• 函数式编程版本：同样提供 lodash-es/fp 的函数式变体

生态图

相关生态

打包工具支持情况

适用场景

• 现代前端项目：使用 Vite、Webpack 5 等支持 tree-shaking 的打包工具的项目
• 包体积敏感场景：移动端、PWA、低带宽环境等对 JS 体积有严格要求的场景
• 按需使用少量函数：只使用 Lodash 的部分功能（如 debounce、cloneDeep），不希望全量引入
• ESM-first 项目：纯 ES Module 项目，无法使用 CommonJS 的场景
• 存量项目优化：从 import _ from 'lodash' 迁移到按需导入以减小打包体积
• SSR/SSG 项目：Next.js、Nuxt 等服务端渲染场景中使用
• 库/框架开发：开发 npm 包时依赖 Lodash 工具函数，避免给消费者带来过大体积负担

开发与工程化

导入方式对比

// ✅ 方式1：解构导入（推荐，tree-shaking 友好）
import { debounce, cloneDeep } from 'lodash-es';
 
// ✅ 方式2：单独导入（同样支持 tree-shaking）
import debounce from 'lodash-es/debounce';
import cloneDeep from 'lodash-es/cloneDeep';
 
// ❌ 方式3：全量导入（无法 tree-shaking）
import _ from 'lodash-es';
_.debounce(fn, 300);

ESLint 规则推荐

// .eslintrc.js
module.exports = {
  rules: {
    // 禁止全量导入 lodash
    'no-restricted-imports': ['error', {
      paths: [{
        name: 'lodash',
        message: '请使用 lodash-es 按需导入',
      }],
    }],
  },
};

Jest 测试配置

lodash-es 在 Jest 中可能遇到 ESM 兼容问题，需要额外配置：

// jest.config.js
module.exports = {
  transformIgnorePatterns: [
    'node_modules/(?!lodash-es)',
  ],
  // 或使用 babel-plugin-lodash 将 lodash-es 转为 lodash
};

性能与安全

性能特点

• Tree-shaking 效果：按需导入时，最终打包体积可减少 90%+（仅包含实际使用函数的代码）
• 运行时性能：与 Lodash 主包完全一致，无性能差异
• 构建性能：ESM 的静态分析可能略微增加打包工具的分析时间，但影响可忽略

安全注意事项

• 版本同步：lodash-es 与 lodash 同步发布，CVE 修复同时覆盖
• CVE-2026-2950：影响 v4.17.23 及更早版本，建议升级到 v4.18.1+
• 安全建议与 Lodash 主包一致

体积优化对比

技术对比

最佳实践

推荐模式

// ✅ 推荐：解构导入
import { debounce, cloneDeep, get, set } from 'lodash-es';
 
// ✅ 推荐：在 Next.js/Vite 项目中使用
// 无需额外配置，默认 tree-shaking 生效
import { uniqueId } from 'lodash-es';
 
// ✅ 存量项目迁移路径
// 第一步：从 lodash 切换到 lodash-es
import { debounce } from 'lodash-es';
// 第二步：评估是否迁移到 es-toolkit

常见陷阱

• ❌ 使用 import _ from 'lodash-es' 全量导入，无法 tree-shaking
• ❌ 混用 lodash 和 lodash-es，可能导致打包工具重复包含代码
• ❌ 在 Jest 中使用 lodash-es 不配置 transformIgnorePatterns，导致测试报错
• ❌ 在 CommonJS 项目中使用 lodash-es（Node.js 需 ESM 支持或 --experimental-modules）
• ❌ 在 next.config.js 的 transpilePackages 中遗漏 lodash-es（某些旧版 Next.js 可能需要）

迁移指南

从 lodash 迁移到 lodash-es：

# 1. 安装 lodash-es
npm install lodash-es
npm uninstall lodash
 
# 2. 全局替换导入语句
# 将 import _ from 'lodash' 替换为 import { fn } from 'lodash-es'

从 lodash-es 迁移到 es-toolkit（可选）：

# es-toolkit 提供 compat 模式，100% 兼容 lodash API
npm install es-toolkit

技术局限与边界

已知限制

• 依赖 Lodash 版本节奏：lodash-es 的更新完全依赖于 Lodash 主包发布节奏
• Jest ESM 问题：在 Jest 测试环境中使用 lodash-es 需要额外配置 ESM 转换
• 非 ESM 环境不可用：纯 CommonJS 环境（旧版 Node.js）无法直接使用
• 不减少运行时开销：tree-shaking 只影响打包体积，运行时性能与 Lodash 一致
• 部分打包工具配置问题：某些情况下 Vite/Webpack 可能无法正确 tree-shake lodash-es，需要检查配置

不适用场景

• 纯 CommonJS 项目（应使用 lodash 主包）
• 需要极致性能和最小体积的新项目（考虑 es-toolkit）
• 对 Jest 测试环境有严格要求且不愿配置 ESM 转换的项目

迁移注意事项

• 迁移前确保打包工具支持 ESM tree-shaking（Webpack 4+、Vite、Rollup）
• 验证构建产物体积确实减小（使用 webpack-bundle-analyzer 或 rollup-plugin-visualizer）
• Jest 项目需额外配置 transformIgnorePatterns
• 混用 lodash 和 lodash-es 会导致打包工具重复包含代码，应统一使用一种

学习资源

• Lodash 官方文档
• lodash-es npm 包
• 掘金：lodash vs. lodash-es 模块化分析
• 掘金：lodash 到 lodash-es 深入源码看 ES Module
• Dev.to: Optimize Core Web Vitals — Tree-shaking Lodash
• Element84: Lessons on Tree-shaking Lodash with Webpack
• GitHub Discussion: Tree Shaking with lodash-es in Vite
• npm-compare: lodash vs lodash-es

2026 年现状

最新版本

• v4.18.1（2026 年 4 月 1 日发布），与 Lodash 主包同步
• 修复了原型污染安全漏洞（CVE-2026-2950）

发展趋势

• 存量项目主流选择：对于已有 Lodash 依赖的项目，lodash-es 是实现 tree-shaking 的最低成本方案
• 新项目替代方案增多：es-toolkit（原生 ESM、2-3x 性能、97% 更小体积）正成为新项目的优先选择
• Lodash 治理改革：2026 年初 Lodash 完成安全 overhaul，lodash-es 同步受益
• 打包工具默认优化：Vite、Webpack 5、Turbopack 等现代打包工具默认支持 ESM tree-shaking，lodash-es 的使用体验持续改善

社区活跃度

• npm 周下载量持续增长（随 Lodash 整体生态）
• GitHub 问题与 Lodash 主包共享，社区讨论活跃
• 作为 tree-shaking 方案的认知度极高

替代趋势

• es-toolkit 的 compat 模式已 100% 兼容 Lodash API，迁移成本极低
• Remeda 在函数式风格工具库领域获得关注
• 原生 JS API（structuredClone、Array.prototype.at、Object.hasOwn 等）持续替代部分 Lodash 功能
• lodash-es 短期仍是存量项目的最佳选择，长期可能逐步被现代替代品取代