npm 常用命令与配置完整速查指南（Quick Reference 项目）

npm 常用命令与配置完整速查指南Quick Reference 项目【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference本文是面向开发者的 npm 快速参考备忘清单源自 Quick Reference 项目GitHub 推荐项目精选 / referen / reference 仓库中的 docs/npm.md。文中系统整理了 npm 的包管理、安装、缓存、更新、发布维护、npx 一次性执行、.npmrc配置、中国镜像站、身份验证以及从 CommonJS 迁移到纯 ESM 包等高频场景的完整命令与配置要点并交叉引用仓库内 semver 语义化版本、package.json 字段详解、Git 忽略规则 等相邻速查文档。读完本文你可以快速查阅并直接复用这些命令解决日常开发中“安装、升级、发布、配置源、跑一次性工具”等绝大多数 npm 实操问题。一、常用命令包管理包管理的核心围绕package.json文件展开常用命令如下| 命令 | 描述 | | :- | :- | |npm init -y| 创建package.json文件-y跳过交互式提问全部采用默认值 | |npm install或npm i| 安装package.json中的所有内容 | |npm install --production| 安装package.json中的所有内容除了devDependencies | |npm install lodash| 安装一个包默认写入dependencies | |npm install --save-dev lodash| 安装为devDependency开发依赖 | |npm install --save-exact lodash| 准确安装锁定精确版本不使用范围运算符 | |npm install scope/package-name| 安装一个作用域scoped的公共包 | |npm install package_nametag| 使用dist-tags发布标签安装包 | |npm install -g package_name| 全局安装包 | |npm uninstall package_name| 卸载包 | |npm uninstall -g package_name| 全局卸载包 |提示npm install --production通常用于生产环境部署场景避免安装开发工具链在 CI/CD 流水线中也可以配合NODE_ENVproduction达到同样效果。安装支持的来源与版本指定npm inpm install的别名可以安装来自不同来源、指定不同版本的包| 命令 | 描述 | | :- | :- | |npm i sax| NPM 包默认从当前 registry 拉取 | |npm i saxlatest| 指定标签最新dist-tag | |npm i sax3.0.0| 指定版本3.0.0| |npm i sax1 2.0| 指定版本范围遵循 semver 范围语法 | |npm i org/sax| 范围内的 NPM 包 | |npm i user/repo| 从 GitHub 安装 | |npm i user/repo#master| 从 GitHub 安装并指定分支/提交 | |npm i github:user/repo| 从 GitHub 安装显式协议写法 | |npm i gitlab:user/repo| 从 GitLab 安装 | |npm i /path/to/repo| 从本地绝对路径安装 | |npm i ./archive.tgz| 从本地压缩包安装 | |npm i https://site.com/archive.tgz| 通过 HTTP 下载压缩包安装 |安装依赖的可用参数-P、--save-prod包将出现在你的dependencies依赖项中这是默认值npm v8 起除非存在-D或-O-D、--save-dev包会出现在你的devDependencies中-O、--save-optional包将出现在你的optionalDependencies中可选依赖安装失败不阻断整体安装参见 package.json.md 中的 optionalDependencies 说明--no-save防止保存到依赖项仅安装、不写入package.json-E、--save-exact依赖项将使用精确版本配置而不是使用 npm 默认的semver范围运算符-B、--save-bundle依赖项也将添加到你的bundleDependencies列表中发布时随包一起打包的包名数组。命令npm i是npm install的别名两者完全等价。清单与版本检查| 命令 | 描述 | | :- | :- | |npm list| 列出此软件中所有依赖项的已安装版本 | |npm list -g --depth 0| 列出所有全局安装包的安装版本--depth 0只显示顶层不递归展开 | |npm view| 列出此软件中所有依赖项的最新版本实际是查看 registry 中包的元信息 | |npm outdated| 仅列出此软件中已过时的依赖项 |其中npm outdated会对比本地已安装版本与 registry 上的最新版本输出Current、Wanted、Latest三列信息帮助你决定是否升级以及升级到哪个范围。缓存管理cache$ npm cache add package-spec # 将指定的包添加到本地缓存 $ npm cache clean [key] # 删除缓存文件夹中的所有数据 $ npm cache ls [nameversion] # 列出缓存中匹配的包条目 $ npm cache verify # 验证缓存文件夹的内容垃圾收集任何不需要的数据 # 并验证缓存索引和所有缓存数据的完整性用于添加、列出或清理 npm 缓存文件夹。日常遇到“缓存损坏导致安装失败”时优先执行npm cache verify做完整性校验必要时再用npm cache clean --force清空缓存。更新与版本号| 命令 | 描述 | | :- | - | |npm version version| 更改package.json中的版本号同时打上对应 Git tag | |npm update| 更新生产包 | |npm update --dev| 更新开发包 | |npm update -g| 更新全局包 | |npm update lodash| 更新lodash包 |npm update只会把依赖更新到package.json中声明的 semver 范围内允许的最新版本并不会跨越大版本关于^、~、等范围运算符的具体语义可参阅 semver 备忘清单。杂项功能# 将某人添加为所有者 $ npm owner add USERNAME PACKAGENAME # 列出包 $ npm ls # 向安装旧版本软件包的用户添加警告弃用 $ npm deprecate PACKAGE 0.2.0 critical bug fixed in v0.2.0 # 更新所有包或选定的包 $ npm update [-g] PACKAGE # 检查过时的包 $ npm outdated [PACKAGE]npm deprecate会在安装匹配版本范围的包时向用户展示弃用警告是发布安全修复后引导用户升级的常用手段。取消发布包unpublish$ npm unpublish package-name -f # 强制取消发布整个包 $ npm unpublish package-nameversion # 取消发布指定版本注意如果你取消发布整个包则必须在 24 小时后才能发布该包的任何新版本。取消发布操作影响范围大请谨慎使用优先考虑用npm deprecate标记弃用。更改包可见性access# 将公共包设为私有 $ npm access restricted package-name # 公开私有包 $ npm access public package-name # 授予私有包访问权限 $ npm owner add user your-package-namenpm access用于管理包的公开/私有状态以及团队成员访问权限私有包与作用域包scope/xxx配合使用最为常见。将包转移到 npm 用户帐户# 新维护者接受邀请 $ npm owner add their-username package-name # 删除维护者 $ npm owner rm your-username package-name # 写入启用了双因素身份验证2FA的维护者 $ npm owner add their-username package-name --otp123456当目标账号启用了 2FA 时需要通过--otp传入一次性验证码才能完成所有权变更。发布包到 npmjs.org$ npm publish # 第一次需要指定公开参数作用域包默认私有 $ npm publish --access public $ npm publish --access public --tag previous--access public首次发布作用域包scope/xxx时必须显式指定为公开--tag previous使用自定义dist-tag发布避免新版本直接成为latest适合先行发布候选版本。关于发布时使用到的private、publishConfig等字段可参阅 package.json.md 发布章节。使用 nrm 切换 registry$ npm install -g nrm # 安装 nrm 包 $ nrm ls # 查看 registry 列表 $ nrm use cnpm # 将注册表切换到 cnpmnrmnpm registry manager提供了交互式切换 registry 的能力适合在网络环境差异较大的团队中快速切换官方源与镜像源。npm init用于设置新的或现有的 npm 包$ npm init package-spec # (如同 npx package-spec) $ npm init scope # (如同 npx scope/create)别名create、innit。npm init支持直接运行脚手架包来初始化项目|npm init foo|npm exec create-foo| | :- | :- | |npm init usr/foo|npm exec usr/create-foo| |npm init usr|npm exec usr/create| |npm init usr2.0.0|npm exec usr/create2.0.0| |npm init usr/foo2.0.0|npm exec usr/create-foo2.0.0|npm exec该命令允许你在与通过npm run运行它类似的上下文环境中从 npm 包执行命令$ npm exec -- pkg[version] [args...] $ npm exec --packagepkg[version] -- cmd [args...] $ npm exec -c cmd [args...] $ npm exec --packagefoo -c cmd [args...]别名x。$ npm exec --package yo --package generator-node --call yo node $ npm exec --packagefoo -- bar --bar-argument # ~ 或 ~ $ npx --packagefoo bar --bar-argument二、npx从本地或远程 npm 包运行命令介绍npx用于从本地或远程 npm 包运行命令无需提前全局安装npx -- pkg[version] [args...] npx --packagepkg[version] -- cmd [args...] npx -c cmd [args...] npx --packagefoo -c cmd [args...]npx二进制文件在npm v7.0.0中被重写当时已不推荐使用独立的npx包后续版本中 npx 作为 npm 内置命令随 npm 一起分发。其核心价值在于免安装运行工具$ npm install eslint # 传统方式运行 $ ./node_modules/.bin/eslint上面命令可以简化直接运行下面命令$ npx eslint命令npx eslint会自动在本地node_modules/.bin中查找并运行eslint如果本地没有则自动临时安装并运行不会污染全局环境。npx VS npm exec$ npx foolatest bar --packagenpmcli/foo # npm 将解析 foo 包名并运行以下命令 $ foo bar --packagenpmcli/foo由于 npm 的参数解析逻辑运行下面这个命令的结果是不同的$ npm exec foolatest bar --packagenpmcli/foo # npm 将首先解析 --package 选项 # 解析 npmcli/foo 包 # 然后它将在该上下文中执行以下命令 $ foolatest bar下面命令是与npx等效的写法$ npm exec -- foolatest bar --packagenpmcli/foo # 等效于 $ npx foolatest bar --packagenpmcli/foo关键区别在于参数解析顺序npx把--package之后的内容当作命令参数原样透传而npm exec会先解析--package选项本身。npx 实战示例使用提供的参数在本地依赖项中运行tap测试框架的指定版本$ npm exec -- tap --bail test/foo.js $ npx tap --bail test/foo.js通过指定--package选项运行命令名称与包名称不匹配的命令$ npm exec --packagefoo -- bar --bar-argument # ~ 或 ~ $ npx --packagefoo bar --bar-argument在当前项目的上下文中运行任意 shell 脚本$ npm x -c eslint say hooray, lint passed $ npx -c eslint say hooray, lint passed用 npx 初始化框架项目创建一个 React Native 项目$ npx react-native init AwesomeProject $ npx react-native init AwesomeTSProject --template react-native-template-typescript使用npx直接创建一个 React 应用跳过手动安装 CRA 的步骤$ npx create-react-app my-app $ npx create-react-app my-app --template typescript这种“下载即用”的方式让脚手架工具保持最新同时不残留全局依赖是当前社区的主流初始化姿势。三、配置 npm.npmrc 配置文件优先级| 文件 | 说明 | | :- | :- | |/path/to/project/.npmrc| 每个项目的配置文件优先级最高 | |~/.npmrc| 每个用户的配置文件 | |$PREFIX/etc/npmrc| 全局配置文件 | |/path/to/npm/npmrc| npm 内置配置文件优先级最低 |配置项按“项目级 用户级 全局 内置”的优先级生效项目级配置可以覆盖用户级与全局配置。配置内容语法# last modified: 01 Jan 2016 ; Set a new registry for a scoped package myscope:registryhttps://registry.npmmirror.com注释使用#、;放置到一行的开头.npmrc文件由指定此注释语法的npm/ini解析器解析。上面的示例为myscope作用域单独指定了镜像 registry其余包仍走默认源。常用 registry 一览| 名称 | registry 地址 | | :- | :- | |npm|https://registry.npmjs.org/| |yarn|https://registry.yarnpkg.com/| |tencent|https://mirrors.cloud.tencent.com/npm/| |cnpm|https://r.cnpmjs.org/| |taobao|https://registry.npmmirror.com/| |npmMirror|https://skimdb.npmjs.com/registry/|.npmignore 发布排除文件将下面内容存放到.npmignore文件中放置在项目的根目录中.git .svn # 忽略 .swp 后缀的文件 .*.swp /logs/* # 意思是不要忽略 !logs/.gitkeep.npmignore文件就像.gitignore一样工作支持#注释、!否定模式、/目录匹配等规则完整语法见 Git 忽略文件速查。但它不能覆盖package.json#files字段——files白名单的优先级更高。中国镜像站安装临时使用镜像源安装某个包# 临时使用 $ npm install -g package-name --registryhttps://registry.npmmirror.com将配置放置在.npmrc全局配置文件中或者放在项目的根目录; registryhttps://registry.npmjs.org/ registryhttps://registry.npmmirror.com或者配置到package.json#publishConfig字段上仅发布时生效publishConfig: { registry: https://registry.npmmirror.com }替换 npm 仓库地址为 npmmirror淘宝镜像地址的持久化写法$ npm config set registry https://registry.npmmirror.com关于publishConfig的完整说明这是一组将在发布时使用的配置值可以覆盖任何配置值但只有tag、registry和access对发布最为重要参见 package.json.md 的 publishConfig 小节。electronjs 镜像与缓存ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRRORhttps://npmmirror.com/mirrors/electron-builder-binaries/ ; ELECTRON_CUSTOM_DIR{{ version }}将上述环境变量写入.npmrc或环境配置可加速 Electron 二进制文件与electron-builder相关二进制资源在国内的下载。身份验证相关配置//registry.npmjs.org/:_authTokenMYTOKEN ; 将适用于 myorg 和 another //somewhere.com/:_authTokenMYTOKEN ; 将适用于 myorg //somewhere.com/myorg/:_authTokenMYTOKEN1 ; 将适用于 another //somewhere.com/another/:_authTokenMYTOKEN2_authToken支持按“主机”或“主机 作用域路径”粒度精确控制配置在//host/层级则对该主机下所有作用域生效配置在//host/scope/层级则只对该作用域生效可用于在同一私有仓库中为不同团队分配不同的访问令牌。四、迁移到纯 ESM 包将 CommonJS 项目迁移到 ESM将type: module添加到你的 package.json将 package.json 中的main: index.js替换为exports: ./index.js将 package.json 中的engines字段更新为 Node.js 14node: 14.16不包括Node.js 12因为它已不再受支持删除所有 JavaScript 文件中的use strictESM 默认即严格模式将所有require()/module.export替换为import/export仅使用完整的相对文件路径进行导入import x from .;→import x from ./index.js;如果你有 TypeScript 类型定义例如index.d.ts请将其更新为使用 ESM 导入/导出可选但推荐使用node:导入协议例如import fs from node:fs以明确区分内置模块与第三方包。TypeScript 项目输出 ESM确保你使用的是 TypeScript 4.7 或更高版本将type: module添加到你的 package.json将 package.json 中的main: index.js替换为exports: ./index.js将 package.json 中的engines字段更新为 Node.js 14node: 14.16不包括Node.js 12因为它已不再受支持将module: node16、moduleResolution: node16添加到你的 tsconfig.json仅使用完整的相对文件路径进行导入import x from .;→import x from ./index.js;删除namespace使用并改用export可选但推荐使用node:导入协议即使你正在导入.ts文件也必须在相对导入中使用.js扩展名TypeScript 在 Node16 模块解析下要求如此。迁移提示ESM 与 CJS 是两种不同的模块解析体系混合使用容易出现“Named export not found”或双实例问题对于已有大量require()的存量项目可以先用node:协议规范内置模块导入再逐步替换第三方依赖的导入写法。相关速查清单Semver 语义化版本速查^、~、、-等版本范围运算符的完整对照表配合npm install与package.json使用package.json 字段详解bundledDependencies、publishConfig、private、optionalDependencies、engines等发布与依赖相关字段的完整说明Git 忽略文件规则.gitignore语法详解与.npmignore规则高度互通TypeScript 速查TS 项目迁移 ESM 时tsconfig.json相关配置可参考本清单。【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考