npm（Node Package Manager）是 Node.js 的官方包管理器，也是 世界上最大的软件注册中心。它于 2010 年由 Isaac Z. Schlueter 创建，随 Node.js 一起分发。npm 包含三个主要组件：
https://registry.npmjs.org/npm 命令调用npm 与 Node.js 紧密集成。安装 Node.js 时会自动安装 npm，二者由 OpenJS Foundation 共同维护。npm 解决了 Node.js 开发中的核心问题：
npm run 执行自定义脚本，构建自动化工作流在 npm 出现之前，JavaScript 开发者需要手动下载库文件并将其包含在项目中，管理依赖关系极其困难。npm 的出现彻底改变了这一局面——它通过中央 registry 和声明式 package.json 文件，将依赖管理从手动操作转变为声明式、自动化的流程。这一模式后来被 pip、RubyGems、Cargo 等几乎所有现代语言的包管理器所借鉴。
npm 生态不仅仅是一个包管理器，它构建了一个完整的 JavaScript 开发基础设施：
| 生态组件 | 说明 | 典型工具/平台 |
|---|---|---|
| 包注册中心 | 存储和分发包的中央仓库 | npmjs.com, GitHub Packages, 私有 registry |
| 命令行工具 | 管理包的生命周期 | npm CLI, npx |
| 包格式 | 标准化的包结构和元数据 | package.json, node_modules |
| 版本系统 | 基于 semver 的版本管理 | package-lock.json, npm update |
| CI/CD 集成 | 在持续集成中使用 npm | npm ci, GitHub Actions, CircleCI |
| 安全审计 | 依赖安全审查和修复 | npm audit, npm fund |
除了 npm，JavaScript 生态中还有其他流行的包管理器。以下是它们的核心对比：
| 特性 | npm | Yarn | pnpm |
|---|---|---|---|
| 发布时间 | 2010 | 2016 | 2017 |
| 安装策略 | 扁平化 node_modules | 扁平化 + PnP 模式 | 硬链接 + 内容寻址存储 |
| 磁盘效率 | 中（每个项目独立安装） | 中（与 npm 类似） | 高（全局存储 + 硬链接） |
| 安装速度 | 中 | 快（并行下载） | 极快（缓存优化） |
| lock 文件 | package-lock.json | yarn.lock | pnpm-lock.yaml |
| 严格模式 | 默认不严格 | 默认不严格 | 严格（防止非法访问） |
| 工作空间 | 支持（推荐） | 支持（原生） | 支持（原生） |
对于个人项目和新手，推荐使用 npm——它随 Node.js 一起安装，无需额外设置，生态系统最成熟。对于大型 monorepo 项目，推荐使用 pnpm 或 Yarn Workspaces。对于磁盘空间敏感的环境，pnpm 的硬链接方案优势明显。
安装 npm 的最简单方式是安装 Node.js。推荐使用以下方式：
访问 https://nodejs.org 下载 LTS（长期支持）版本安装包。LTS 版本经过充分测试，适合生产环境。
nvm（Node Version Manager）允许在同一台机器上安装和切换多个 Node.js 版本，是 开发环境的首选方案。
在项目中创建 .nvmrc 文件指定 Node.js 版本，团队成员只需运行 nvm use 即可切换到正确版本：
npm 自带了更新自身的功能。不同的 Node.js 版本捆绑了不同的 npm 版本：
npm 的配置系统非常灵活，支持多级配置（从全局到项目级别）：
https://registry.npmmirror.com），通常会大幅提升包下载速度。但注意，某些企业级包发布平台（如 GitHub Packages）需要特定的 registry 配置，可以通过 --registry 参数或项目级 .npmrc 实现混合配置。
.npmrc 是 npm 的配置文件，可以存在于多个层级，按优先级从高到低排列：
.npmrc（最高优先级）~/.npmrc（当前用户的全局配置）etc/npmrc切勿将包含认证令牌（auth token）的 .npmrc 文件提交到版本控制系统。使用环境变量或 secrets 管理工具来存储敏感信息。建议将 .npmrc 添加到 .gitignore，或使用 .npmrc.template 作为示例文件。
npm init 是创建新项目的起点，它会引导你生成 package.json 文件：
npm init <initializer> 是 npm 6.1+ 引入的强大功能。当运行 npm init foo 时，npm 会自动执行 npx create-foo，创建一个模板项目。这意味着像 npm init vite、npm init next-app 等命令可以直接使用，无需全局安装脚手架工具。
这是最常用的 npm 命令，用于安装项目依赖：
npm install 会根据 package.json 中的 semver 范围解析最新兼容版本，并更新 lock 文件。而 npm ci 完全按照 lock 文件安装，速度更快，适合 CI/CD 环境。在 CI 中始终使用 npm ci，不要使用 npm install，以确保构建的可重复性。
根据 package.json 中定义的 semver 范围更新已安装的包：
扫描项目依赖中的已知安全漏洞：
| 命令 | 功能 | 使用场景 |
|---|---|---|
npm ci |
从 lock 文件精确安装 | CI/CD 环境、生产部署 |
npm publish |
发布包到 registry | 发布 npm 包 |
npm link |
本地开发时链接包 | 调试本地依赖 |
npm cache |
管理 npm 缓存 | 清理或验证缓存 |
npm pack |
打包为 .tgz 文件 | 发布前测试 |
npm dedupe |
去重重复依赖 | 优化 node_modules |
npm doctor |
诊断环境问题 | 排查 npm 环境故障 |
package.json 是 npm 项目的核心元数据文件，位于项目根目录：
| 字段 | 说明 | 是否必需 |
|---|---|---|
name |
包名称，必须唯一且符合命名规范（小写、连字符） | 是（发布时需要） |
version |
当前版本号，遵循 semver 规范 | 是（发布时需要） |
description |
包的简短描述，有利于搜索结果 | 推荐 |
main |
包的入口文件路径 | 推荐 |
scripts |
可执行的 npm 脚本定义 | 常用 |
dependencies |
生产环境依赖 | 常用 |
devDependencies |
开发环境依赖（测试、构建工具等） | 常用 |
peerDependencies |
宿主依赖（插件开发时指定） | 特定场景 |
engines |
指定兼容的 Node.js 版本 | 推荐 |
semver 格式为 主版本号.次版本号.补丁号（如 4.18.2）。版本变更的含义：
npm 支持多种版本范围的写法：
| 写法 | 含义 | 示例匹配 |
|---|---|---|
^4.18.0 |
兼容主版本，允许更新次版本和补丁 | 4.18.0 ~ 4.x.x（不含 5.0.0） |
~4.18.0 |
兼容次版本，只允许补丁更新 | 4.18.0 ~ 4.18.x |
4.18.0 |
精确版本，不允许任何偏差 | 仅 4.18.0 |
>=4.18.0 <5.0.0 |
范围表达式 | 4.18.0 ~ 4.x.x |
* |
任意版本 | 任何版本 |
latest |
最新发布的版本 | registry 中的最新版本 |
在 生产环境 中，建议使用 lock 文件（package-lock.json）来锁定所有依赖的精确版本。在 开发库 中，dependencies 应使用宽松的版本范围（如 ^），以兼容宿主项目的版本。使用 npm config set save-exact=true 可以在安装时自动保存精确版本。
理解二者的区别至关重要：
express、react、lodash。通过 npm install <package>（不加 -D）安装。typescript、jest、eslint。通过 npm install -D <package> 安装。使用 npm install --production 或设置 NODE_ENV=production 时，只有 dependencies 会被安装，这在 CI/CD 部署流程中可以显著减少安装时间和磁盘占用。
package-lock.json 是在调用 npm install 时自动生成的文件，记录了依赖树的 精确版本和完整性哈希值。它的核心作用：
package-lock.json 必须被提交到版本控制系统中！这是确保团队成员和生产环境使用相同依赖版本的关键。不要将 lock 文件添加到 .gitignore 中。如果 lock 文件未被跟踪，每个开发者可能安装到不同的依赖版本，导致"在我机器上能运行"的问题。
scripts 字段是 package.json 中最强大的功能之一，它允许开发者定义一系列可以通过 npm run 执行的命令：
npm 为一些常用命令提供了简写：npm start、npm test、npm stop、npm restart 可以直接运行，无需 run 关键字。
npm 会自动为每个脚本生成 pre 和 post 钩子。当运行 npm run build 时，npm 会按以下顺序自动执行：
prebuild —— 构建前执行的脚本build —— 主构建脚本postbuild —— 构建后执行的脚本npm 定义了多个内置生命周期事件。除了 build 和 test，以下生命周期也支持 pre/post 钩子：install、uninstall、publish、version、pack、shrinkwrap 等。这些钩子可以用来自动化版本管理（如发布前自动运行测试、更新 changelog 等）。
npx 是 npm 5.2+ 自带的包执行工具。它允许直接运行 npm registry 中的包，而无需事先安装：
npx create-react-app 而不是 npm install -g create-react-app 可以避免全局包版本冲突，且每次使用都能获取最新版本。在 CI 环境中，npx 可以避免安装不必要的全局工具，减少构建时间。
| 模式 | 脚本示例 | 说明 |
|---|---|---|
| 开发服务器 | "dev": "vite" |
启动热重载开发服务器 |
| 生产构建 | "build": "tsc && vite build" |
先编译 TS 再构建 |
| 并行任务 | "dev": "concurrently \"npm run server\" \"npm run client\"" |
同时运行前后端 |
| 参数传递 | "test": "jest --passWithNoTests" |
传递额外参数 npm run test -- --watch（使用 -- 分隔） |
| 环境变量 | "start": "NODE_ENV=production node index.js" |
设置环境变量（Windows 需要 cross-env） |
由于 Windows 和 Unix 系统设置环境变量的语法不同（SET NODE_ENV=production vs NODE_ENV=production），推荐使用 cross-env 包实现跨平台兼容：
要发布 npm 包，首先需要注册 npm 账号：
切勿在 CI 配置或代码中硬编码 npm token。使用 CI/CD 平台提供的 secrets 管理功能（如 GitHub Secrets）来存储 NPM_TOKEN。在 .npmrc 中使用 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 引用环境变量。
发布一个 npm 包的标准流程：
package.json 包含 name、version、main 等必要字段npm pack 生成 .tgz 文件，检查包内容是否正确npm version 命令更新版本号npm publishnpm 的 dist-tag 机制允许为同一包的不同版本添加标签：
| 标签 | 用途 | 说明 |
|---|---|---|
latest |
最新稳定版 | 默认标签，npm install 安装此版本 |
next |
下一个候选版本 | 发布预发布版本时使用 |
beta |
Beta 测试版 | 需要社区测试的新功能 |
alpha |
内部测试版 | 不稳定的早期版本 |
legacy |
旧版维护 | 已弃用的旧版本 |
当包不再维护或存在安全问题时，应弃用特定版本：
命名格式为 @组织名/包名，如 @angular/core、@vue/cli：
npm 内置了强大的安全审计功能：
--audit-level 设置报告阈值，例如 npm audit --audit-level=high 只在存在高或严重漏洞时退出码为非零。
遵循最小权限原则来管理 npm 操作：
sudo npm install -gnpm outdated 查看可更新依赖，有计划地升级使用第三方 registry 时需要注意安全问题：
| 安全措施 | 说明 | 实现方式 |
|---|---|---|
| HTTPS 通信 | 确保 registry 通信加密 | 默认 npm registry 使用 HTTPS |
| 完整性校验 | 验证包内容未被篡改 | lock 文件中的 integrity 哈希值 |
| 签名验证 | 验证发布者身份 | npm registry 支持包签名 |
| 私有 registry | 企业内部包隔离 | Verdaccio、GitHub Packages、AWS CodeArtifact |
| 依赖审查 | 防止恶意包混入 | Socket.dev、npm audit、Snyk |
npm 生态的开放性也带来了供应链攻击的风险。典型风险包括：依赖混淆攻击（将恶意包发布到公共 registry，名称与内部私有包相同）、恶意包名混用（如 event-stream 被植入恶意代码）。应对措施：使用 --registry 明确作用域包的 registry 来源，定期审计依赖，使用 npm fund 了解包的维护状况。
package-lock.json 纳入版本控制npm ci 而非 npm installnpm audit 集成到 CI 流程中^ 范围package.json 中设置 engines 字段npm outdated 和 npm fund 了解包的健康状况npx 替代全局工具安装Claude Code 可以自动执行 npm 命令来管理项目依赖。以下是在 Claude Code 工作流中使用 npm 的典型场景：
在 Claude Code 中，当你编写代码并使用了一个 npm 包时，可以通过以下方式让 Claude Code 自动安装依赖：
npm install axios在 Claude Code 中，使用以下提示词可以获得更好的 npm 管理体验：
Claude Code 可以根据项目需求自动生成完整的 package.json 文件：
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 安装慢或失败 | 网络问题、registry 访问慢 | 切换到国内镜像：npm config set registry https://registry.npmmirror.com |
| 版本冲突 | 依赖包的 semver 范围不兼容 | 使用 npm ls <package> 查看依赖树，使用 npm dedupe 去重 |
| 缺失依赖 | peerDependencies 未安装 | 运行 npm install --legacy-peer-deps 或手动安装 peer 依赖 |
| 权限错误 | 全局安装时权限不足 | 配置 npm prefix 到用户目录，避免使用 sudo |
| lock 文件冲突 | 多人修改 package.json 导致 lock 文件不一致 | 运行 npm install 重新生成 lock 文件 |
| ENOENT 错误 | node_modules 损坏或缓存问题 | 删除 node_modules 和 lock 文件，重新安装 |
当遇到 npm 相关问题时，可以指示 Claude Code 按以下顺序排查：先检查 Node.js 和 npm 版本是否匹配 → 检查 registry 配置是否正确 → 检查 package.json 格式 → 删除 node_modules 和 lock 文件重新安装 → 使用 npm cache clean --force 清理缓存。这种系统化的排查方法可以高效地解决大多数 npm 问题。
^、~、精确版本的区别，以及 lock 文件的作用，是避免"依赖地狱"的关键。npm audit、启用 2FA、提交 lock 文件、使用 npm ci 是最基本的安全实践。npm ci 而非 npm install，确保构建的可重复性和速度。