guide

es-toolkit 使用指南

介绍如何在不同运行时中安装、导入和使用 es-toolkit。

输入

$ARGUMENTS — 关于 es-toolkit 用法的主题或问题。

为何要以权威来源为准

安装命令和导入路径会随版本变化。如果已安装 es-toolkit，请从已安装的包中确认其版本和导出内容。此技能可能作为独立目录安装，因此绝不要假设 es-toolkit 仓库或同级的 docs 目录可用。

工作流程

1. 检查用户的项目

根据锁文件识别包管理器：

• package-lock.json → npm
• yarn.lock → Yarn
• pnpm-lock.yaml → pnpm
• bun.lock 或 bun.lockb → Bun

如果已安装 es-toolkit，请从依赖它的包中解析其包元数据：

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

从相关工作区包中运行命令，而不是默认从 monorepo 根目录运行。如果项目使用 Yarn Plug'n'Play，请使用 yarn node，而不是 node。读取解析出的 package.json，以确认已安装的版本及其 exports。

如果命令因尚未安装 es-toolkit 而失败，请继续查看下方的安装说明；不要搜索仓库相对路径下的文件。

2. 根据用户的环境作答

识别运行时（Node.js、Bun、Deno、浏览器），并提供适用于该环境的说明。

稳定的设置信息：

• Deno：deno add jsr:@es-toolkit/es-toolkit（注意 jsr: 前缀）
• Deno 导入路径：'@es-toolkit/es-toolkit'（比 npm 多一层作用域）
• npm/yarn/pnpm/bun：提供与检测到的包管理器匹配的命令。如果没有锁文件，请询问用户偏好的包管理器，或列出可用命令。
• 导入路径：严格模式使用 'es-toolkit'，与 lodash 兼容的模式使用 'es-toolkit/compat'
• 浏览器/CDN：jsdelivr 和 unpkg 提供 UMD 构建（_ 全局变量），而 esm.sh 提供 ES 模块。请链接到下方的官方用法页面，获取最新代码示例。

3. 按需涵盖以下主题

• 安装：针对各运行时提供命令
• 导入模式：命名导入（推荐用于摇树优化）、分类导入和 compat 导入。如果已安装该包，请从解析出的包 exports 中列出可用的子路径导入，而不是使用记忆中的列表。
• 应避免的反模式：警告用户不要使用命名空间导入（import * as _ from 'es-toolkit'），因为这会妨碍摇树优化。始终优先使用命名导入（import { chunk, debounce } from 'es-toolkit'）。
• 包体积和性能：链接到下方的官方页面。只有当用户提供了具体数字，或当前仓库检出版本中包含基准测试数据时，才引用精确数字；不要在技能中保留过时数据。
• 类型安全：包中包含内置的 TypeScript 类型声明。

4. 仅在仓库文档存在时使用

如果当前项目是 es-toolkit 源代码仓库，则 docs/ 和 src/ 下的本地文件具有权威性，可供搜索。否则，请使用已安装包的元数据和类型声明。绝不要假设此技能旁边存在 docs 目录。

5. 始终包含文档链接

在回复结尾附上相关链接：

## Learn More
- Documentation: https://es-toolkit.dev/intro.html
- Usage: https://es-toolkit.dev/usage.html
- Bundle size: https://es-toolkit.dev/bundle-size.html
- Performance: https://es-toolkit.dev/performance.html
- GitHub: https://github.com/toss/es-toolkit