📦 npm：Node.js 的超级包管家🧩 1 基础命令宝典 npm init：初始化项目目录，创建核心配置文件

npm 是 Node.js 的核心包管理工具，它让 JavaScript 项目的依赖管理变得轻松高效。

🧩 1 基础命令宝典

npm init：初始化项目目录，创建核心配置文件 package.json。
npm install / uninstall：安装/卸载依赖包。
- npm install <package>：安装最新版本。
- --save (-S)：安装为普通依赖 (写入 dependencies)。
- --save-dev (-D)：安装为开发依赖 (写入 devDependencies)。
- --global (-g)： 全局安装，常用于命令行工具。
npm config：管理 npm 配置。
- set/get/delete：设置/获取/删除配置项。
- registry：关键配置！设置镜像源（如淘宝源 https://registry.npmmirror.com），解决国内访问 npm 官方仓库慢的问题。
- list：列出所有当前配置。
npm run：执行 package.json 中 scripts 部分定义的自定义脚本 (如 npm run dev)。
npm update：更新指定的包到符合 package.json 版本规则的最新版本。
npm outdated：列出项目中已过时（有更新版本）的包。
npm login / logout：登录/登出 npm 账号（发布包前必需）。
npm publish：将当前目录下的包发布到 npm 仓库。
npm link：在本地链接 npm 包进行开发和测试，非常方便本地调试。
npm list (ls)：列出当前项目安装的所有包及其依赖树。
npm search：在 npm 仓库中搜索指定名称的包。
npm audit：检查项目依赖中的安全漏洞并提供修复建议。
... 以及其他众多实用命令（如 npm ci, npm view, npm docs 等）。

📝 2 package.json：项目的身份证与说明书

package.json 文件是 npm 项目的核心配置文件，它定义了项目的基本信息、依赖、脚本等一切重要内容。

✨ 2.1 核心配置项

name：项目名称（必填，需符合 npm 命名规则）。
description：项目描述，简洁说明项目是做什么的。
version：项目版本号（必填），遵循 主版本.次版本.修订号 的 Semver (语义化版本) 规范。
type：指定模块系统 ("commonjs" 或 "module")，影响 import/require 的使用方式。
main：项目的主入口文件路径（通常是 index.js 或 lib/index.js），当用户 require('your-package') 时会加载此文件。
module：（可选）指向 ES 模块格式的入口文件，供支持 ES Module 的打包工具（如 Webpack, Rollup, Vite）使用。
browser：（可选）指定在浏览器环境下替代 main 的入口文件。
scripts： 脚本命令集，项目的“自动化助手”。
- 包含预定义的生命周期命令（如 prepublish, postinstall）。
- 开发者自定义的常用命令（如 start, build, test, dev）。
dependencies： 生产环境依赖列表。项目运行时必需的包，会被自动安装到用户环境。
devDependencies： 开发环境依赖列表。仅在项目开发、构建或测试时需要的包（如 ESLint, Jest, Webpack）。
peerDependencies： 对等依赖列表。声明你的包需要宿主环境（使用你包的项目）提供的特定依赖包（如插件需要宿主安装特定框架版本）。宿主需要手动安装这些依赖。
peerDependenciesMeta：对等依赖的元信息。常用 "optional": true 标记某个对等依赖是可选的（宿主不安装也不会报错，但你的包可能需要做兼容处理）。
repository：项目源代码仓库信息（如 Git URL）。
... 以及其他配置项（keywords, author, license, files, engines, bin 等）。

🧠 2.2 `npm install` 安装原理探秘

npm install（或 npm i）是使用最频繁的命令，它的工作原理值得了解（与 Yarn、pnpm 等工具的设计有显著区别）：

依赖存放地：所有安装的依赖包最终都存放在项目根目录下的 node_modules 文件夹中。
- 安装顺序： .bin (存放 npm 包的可执行文件) -> @开头的组织作用域包 (如 @babel/core) -> 按包名首字母排序 (a, b, c, ...)。
扁平化 (Deduplication)： npm 默认采用扁平化策略安装依赖，目的是减少冗余。
- 原理： npm 会尽量将相同版本的依赖包提升 (hoist) 到 node_modules 的根目录。这样，所有需要这个版本的子依赖都可以直接访问根目录下的这个包，避免了重复安装。
- 算法：使用广度优先 (BFS) 算法遍历依赖树。先处理项目根依赖，再处理每个根依赖的直接子依赖，依此类推。
不完全扁平化 (Nesting)：扁平化不是万能的！
- 问题：如果项目中的不同包依赖了同一个包的不同版本（比如包 A 需要 lodash@^4.0.0，包 B 需要 lodash@^3.0.0），npm 无法将它们都提升到根目录。
- 解决： npm 会将其中一个版本（通常是满足更多依赖要求的版本）提升到根目录，而将另一个冲突的版本安装在其父依赖的 node_modules 目录下（形成嵌套）。这可能导致“幽灵依赖”问题（项目代码可能意外访问到根目录下的包，但无法访问嵌套目录下的包）。
package-lock.json：版本锁定的守护者：为了解决不同环境安装依赖版本不一致的问题（“在我机器上是好的”问题），npm 5 引入了 package-lock.json。
- 作用：它精确地、完整地记录了当前项目 node_modules 树的结构和所有依赖包的确切版本、下载地址、完整性校验码等信息。确保无论何时何地执行 npm install，只要存在 package-lock.json，安装的结果都是完全一致的。
- 关键字段：
  - version：包的精确版本号。
  - resolved：包的实际下载地址（tarball URL）。
  - integrity：包的哈希值 (如 sha512-...)，用于验证下载包的完整性，防止被篡改。
  - dev： true 表示该包是开发依赖。
  - bin：指向该包提供的可执行文件路径。
  - engines：指定该包运行所需的 Node.js 版本范围。
- 缓存机制： npm 利用 package-lock.json 中的 name + version + integrity 信息生成一个唯一的 key。安装时，会优先检查本地缓存目录（通常位于 ~/.npm/_cacache）中是否存在对应的包文件。如果存在且校验通过，则直接从缓存复制，极大加速安装速度。

🏃 3 `npm run` 原理：脚本执行的奥秘

命令查找机制：当你执行 npm run xxx（如 npm run dev）时：
- npm 首先在 package.json 的 scripts 对象中查找名为 xxx 的命令。
- 找到后，它会尝试执行该命令字符串（如 "vite"）。对于这种可执行命令（不是 shell 内置命令），npm 会按照以下路径查找真正的可执行文件：
  1. 当前项目的 node_modules/.bin/ 目录。
  2. 全局安装的 node_modules/.bin/ 目录（即 npm 的全局 bin 目录）。
  3. 系统环境变量 PATH 中定义的目录。
  4. 如果以上都找不到，npm 会报错 command not found。
跨平台兼容性： node_modules/.bin/ 目录下通常会有多个文件指向同一个脚本：
- vite (Unix-like shell 脚本)：适用于 Linux, macOS, WSL。
- vite.cmd (Windows 批处理脚本)：适用于 Windows CMD。
- vite.ps1 (PowerShell 脚本)：适用于 Windows PowerShell。
- npm 会根据你运行命令的终端环境自动选择正确的脚本执行。

生命周期钩子： npm run 支持前置 (pre) 和后置 (post) 钩子脚本。

"scripts": {
    "predev": "node pre-script.js", // 在 `dev` 之前自动运行
    "dev": "vite",                 // 主命令
    "postdev": "node post-script.js" // 在 `dev` 之后自动运行
}

执行 npm run dev 时，实际执行顺序是： predev -> dev -> postdev。

特殊的 prepare 生命周期：
- 这个脚本非常有用，它会在：
  - npm install 之后（不含参数）自动执行。
  - npm publish 之前自动执行。
- 常用于执行一些发布前的准备工作，比如编译 TypeScript 到 JavaScript (tsc)、运行构建命令 (npm run build)。

🚀 4 npx：无需安装的临时执行器

npx 是一个随 npm 一起安装的实用命令行工具，它的核心作用是方便地执行包。

核心优势：
- 免全局安装：直接运行本地项目 node_modules/.bin 或远程仓库中的包命令，无需先 npm install -g。例如：npx eslint .。
- 总是使用最新版：执行远程包时，npx 会下载并运行其最新版本（除非指定版本），非常适合偶尔使用的工具（如 npx create-react-app my-app）。
- 执行任意 npm 包：即使包本身没有提供全局可执行命令，npx 也能运行其内部脚本（如 npx -p cowsay -p lolcatjs -c 'echo "Hello World" | cowsay | lolcatjs'）。
- 执行 GitHub Gist： npx https://gist.github.com/... (需符合特定格式)。
npm vs npx：
- npm：核心功能是管理包（安装、卸载、更新、发布）。它侧重于包本身在项目或全局环境中的存在状态。
- npx：核心功能是执行包。它侧重于运行包提供的命令，无论这个包是本地已安装的、需要临时下载的，还是全局安装的。它简化了“运行一次”的需求。

📤 5 发布你的 npm 包：分享你的创造

将自己编写的模块发布到 npm 仓库，让全世界（或你的团队）都能使用，好处多多：

发布 npm 包的好处：
- 代码复用：轻松抽离公共逻辑或工具函数，在多个项目中共享。
- 团队协作：方便团队内部或跨团队共享私有或公共组件库、工具库。
- 参与开源：将你的优秀解决方案贡献给社区，建立影响力。
- 版本管理：通过 Semver 规范管理包的迭代和升级。
发布流程：
1. 注册账号：访问 npm 官网注册账号。也可以直接在终端运行 npm adduser 或 npm login，它会引导你完成注册/登录流程（可能需要打开浏览器）。
2. 登录账号：在项目根目录下运行 npm login。根据提示输入你的 npm 账号用户名、密码和邮箱（如果开启了双因素认证，还需输入 OTP）。
3. 准备发布：
  - 确保 package.json 中的 name 是唯一的（在 npm 仓库中不存在）。
  - 确保 version 符合 Semver 规则且是新的（或使用 npm version patch/minor/major 更新版本号）。
  - 检查 .npmignore 文件（或 package.json 中的 files 字段），确保只发布必要的文件（通常不发布 node_modules, 测试文件、配置文件、源码等）。
4. 发布包：在项目根目录下运行 npm publish。 ```
  - 如果是首次发布公共包 ("private": false)，会发布为公共包。
  - 如果想发布私有包（需要付费账户），需在 package.json 中设置 "private": true，并使用 npm publish --access restricted（组织作用域包可能需要特定配置）。
5. 验证：发布成功后，可以在 npm 官网搜索你的包名查看，或者直接使用 npm install <your-package-name> 安装测试。

📦 npm：Node.js 的超级包管家