ni 完全指南 - wangshengliang

ni 是由 Anthony Fu 开发的命令行工具，能够自动检测项目使用的包管理器（npm/yarn/pnpm/bun），并使用对应的命令执行操作。在多项目、多包管理器环境下，不再需要记忆各种命令差异。

🎯 环境说明：本文基于 @antfu/ni v0.23.x 编写。

为什么需要 ni#

🙋 不同项目可能使用不同的包管理器。每次切换项目都要想一下：

这个项目用的是 npm 还是 pnpm？
pnpm 的安装命令是 pnpm add 还是 pnpm install？
yarn 运行脚本要不要 run？

✅ ni 解决了这个问题。只需记住一套命令，ni 会根据 lockfile 自动识别包管理器并调用对应命令。

# 无论项目用的是 npm/yarn/pnpm/bun
$ ni        # 安装依赖
$ nr dev    # 运行脚本
$ nu        # 更新依赖

安装#

$ npm install -g @antfu/ni

# 或
$ pnpm add -g @antfu/ni

# 或
$ yarn global add @antfu/ni

验证安装：

$ ni --version
0.23.0

核心命令#

ni 提供了一组简短的命令，对应不同包管理器的常用操作：

ni 命令	npm	yarn	pnpm	bun	deno
`ni`	`npm install`	`yarn install`	`pnpm install`	`bun install`	`deno install`
`ni pkg`	`npm i pkg`	`yarn add pkg`	`pnpm add pkg`	`bun add pkg`	`deno add pkg`
`nr`	`npm run`	`yarn run`	`pnpm run`	`bun run`	`deno task`
`nu`	`npm update`	`yarn upgrade`	`pnpm update`	`bun update`	`deno upgrade`
`nup`	`npm upgrade`	`yarn up`	`pnpm update`	`bun update`	`deno upgrade`
`nun`	`npm uninstall`	`yarn remove`	`pnpm remove`	`bun remove`	`deno remove`
`nci`	`npm ci`	`yarn --frozen`	`pnpm --frozen`	`bun --frozen`	`deno cache`
`nlx`	`npx`	`yarn dlx`	`pnpm dlx`	`bunx`	`deno run npm:`
`na`	`npm`	`yarn`	`pnpm`	`bun`	`deno`

ni - 安装依赖#

# 安装 package.json 中的所有依赖
$ ni

# 安装指定包（生产依赖）
$ ni lodash

# 安装开发依赖
$ ni -D typescript

# 安装多个包
$ ni express cors helmet

# 冻结安装（CI 环境）
$ ni --frozen

ni 会根据项目中的 lockfile 检测包管理器：

Lockfile	包管理器
`package-lock.json`	npm
`yarn.lock`	yarn
`pnpm-lock.yaml`	pnpm
`bun.lockb`	bun

nr - 运行脚本#

# 运行 dev 脚本
$ nr dev

# 运行带参数的脚本
$ nr test --watch

# 交互式选择脚本
$ nr

# 运行指定脚本，如果不存在则忽略
$ nr build --if-present

不带参数执行 nr 会列出所有可用脚本供选择：

$ nr
? script › - Use arrow-keys. Return to submit.
❯   dev
    build
    test
    lint

nr 的便捷之处#

无论项目用什么包管理器：

# 不用区分 npm run dev / yarn dev / pnpm dev
$ nr dev

nu - 更新依赖#

# 交互式更新
$ nu

# 更新指定包
$ nu lodash

# 更新所有包
$ nu -i

nup - 升级依赖#

# 升级依赖
$ nup

# 交互式升级（不支持 npm/bun/deno）
$ nup -i

nci - 清洁安装#

用于 CI 环境，基于 lockfile 安装精确版本：

$ nci

# npm ci
# yarn install --frozen-lockfile
# pnpm install --frozen-lockfile
# bun install --frozen-lockfile
# deno cache --reload

nun - 卸载包#

# 卸载包
$ nun lodash

# 卸载多个包
$ nun lodash express

nlx - 执行包命令#

# 类似 npx，临时下载并执行
$ nlx create-react-app my-app

# 执行本地包命令
$ nlx eslint src

na - 直接调用包管理器#

当需要执行 ni 没有封装的命令时，使用 na：

# 等同于 npm/yarn/pnpm/bun 的原生命令
$ na cache clean
$ na audit
$ na outdated

全局标志#

ni 支持一些全局标志：

# 打印将要执行的命令（不执行）
$ ni vite ?

# 切换到指定目录执行
$ ni -C packages/foo vite
$ nr -C playground dev

# 显示版本
$ ni -v

# 显示帮助
$ ni -h

全局安装#

# 全局安装包
$ ni -g typescript

# 全局卸载
$ nun -g typescript

检测机制#

ni 按以下顺序检测包管理器：

检查当前目录及父目录的 lockfile
检查 package.json 中的 packageManager 字段
如果都没有，提示选择

使用 packageManager 字段#

在 package.json 中指定包管理器（Corepack 规范）：

{
  "packageManager": "pnpm@9.15.0"
}

ni 会识别并使用指定的包管理器。

配置#

在用户目录创建 ~/.nirc 配置文件：

; 默认使用的包管理器（无 lockfile 时）
defaultAgent=pnpm

; 全局包使用的管理器
globalAgent=npm

配置选项#

选项	说明	默认值
`defaultAgent`	默认包管理器	提示选择
`globalAgent`	全局安装使用的包管理器	npm

实用场景#

多项目开发#

假设你同时维护多个项目：

项目 A：使用 npm
项目 B：使用 yarn
项目 C：使用 pnpm

有了 ni，无需切换思维：

$ cd project-a && ni && nr dev
$ cd project-b && ni && nr dev
$ cd project-c && ni && nr dev

CI/CD 环境#

在 CI 中使用 --frozen 确保依赖版本一致：

# GitHub Actions 示例
- name: Install dependencies
  run: npx @antfu/ni --frozen

- name: Build
  run: npx @antfu/ni run build

脚本中使用#

在 npm scripts 中也可以使用 ni：

{
  "scripts": {
    "setup": "ni",
    "dev": "nr dev"
  }
}

项目模板#

创建项目模板时，使用 ni 命令可以让模板适配任何包管理器：

#!/bin/bash
ni
nr build

与其他工具对比#

工具	特点
ni	自动检测，统一命令
npx	npm 专属，执行包命令
pnpx	pnpm 专属
yarn dlx	yarn 专属
bunx	bun 专属

ni 的优势在于跨包管理器的统一体验。

常用命令速查#

命令	用途
`ni`	安装所有依赖
`ni <pkg>`	安装包
`ni -D <pkg>`	安装开发依赖
`ni -g <pkg>`	全局安装
`ni --frozen`	冻结安装（CI）
`ni -i`	交互式搜索安装
`nci`	清洁安装（CI 推荐）
`nr`	交互式运行脚本
`nr <script>`	运行指定脚本
`nu`	更新依赖
`nu <pkg>`	更新指定包
`nup`	升级依赖
`nup -i`	交互式升级
`nun <pkg>`	卸载包
`nun -m`	交互式多选卸载
`nlx <pkg>`	执行包命令
`na <cmd>`	调用原生包管理器命令
`ni -C <dir>`	切换目录后执行

常见问题#

检测到错误的包管理器#

删除不需要的 lockfile，或在 package.json 中明确指定：

{
  "packageManager": "pnpm@9.15.0"
}

想要强制使用某个包管理器#

使用环境变量：

$ NI_DEFAULT_AGENT=pnpm ni

或在 ~/.nirc 中设置 defaultAgent。

Windows 兼容性#

ni 完全支持 Windows，包括 PowerShell 和 CMD。