npm install与Node.js项目依赖管理

先确认npm属于哪套Node.js

起点是node和npm命令均可运行，目标是项目依赖写入package.json并可正常调用。准备项目目录、npm命令和网络后再继续。

在项目目录打开终端，运行node --version、npm --version、where node和where npm。版本号不需要相同，但路径应属于预期环境。若电脑有多个Node.js版本，直接运行npm可能调用另一套安装中的脚本，从而产生“安装成功但项目仍找不到包”的现象。

本站分发记录为Node.js 16.17.0.0，该版本线已停止维护。维护旧项目时要遵循项目锁定要求；新项目应先选择受支持版本，再开始安装依赖。包是否兼容还要检查其engines声明、发行说明和测试结果，不能只看npm命令是否成功。

初始化项目并理解生成文件

项目初始化的价值是把名称、入口、依赖和可执行命令写进同一份配置。生成文件后应先阅读内容，再继续安装依赖，不把默认值当成不可修改的规则。

1. 1.在空项目目录运行npm init -y生成配置。
2. 2.打开package.json确认名称、版本和scripts字段。
3. 3.安装一个本地依赖并查看配置变化。
4. 4.使用npm ls验证实际依赖树。
5. 5.从新的空目录按锁文件重建并运行项目命令。

mkdir demo-app
cd demo-app
npm init -y

npm init -y会生成基础package.json。其中的名称、版本、入口、scripts和依赖清单都是项目元数据，可以按需要修改。package.json应进入版本控制，因为它描述项目需要什么；安装产生的node_modules通常不提交，因为体积大且可按锁文件重建。

首次安装依赖后通常还会生成package-lock.json。锁文件记录更精确的依赖树，有助于团队和自动化环境得到一致结果。不要把“删除锁文件再装一次”当作默认排错动作；如果确实更新依赖，应了解变化并审查锁文件差异。

使用npm install安装本地依赖

下面的命令表属于项目级工作流：先初始化，再安装，再做依赖验证。完整动作包括npm init -y、检查package.json、npm install示例包、检查node_modules与lock文件、添加并运行script。

npm install lodash
npm ls lodash

默认本地安装会把包放到当前项目的node_modules，并把依赖写入package.json。随后可在脚本中按项目模块格式引入该包。npm ls用于检查实际依赖树，不能只看终端最后一行是否出现成功字样。

开发期间使用、生产运行时不需要的工具可以用npm install 包名 --save-dev记录到开发依赖。全局安装npm install -g适合明确需要系统级命令的工具，不适合作为普通项目库的默认方式。过度依赖全局包会让项目在其他电脑上缺少隐式条件。

用scripts记录项目命令

项目命令写入scripts后，团队成员和自动化环境都可以通过同一入口执行。修改脚本时应同步更新说明，并在干净环境验证命令不依赖本机全局工具。

在package.json中加入启动脚本，比让每个人记住入口参数更可靠：

{
  "scripts": {
    "start": "node app.js",
    "check": "node --check app.js"
  }
}

保存后运行npm run start和npm run check。scripts会优先找到项目本地安装的命令，因此不必把所有开发工具全局安装。团队应在README中说明必要环境变量和启动顺序，敏感值不要直接写入仓库。

npm install失败时按层排查

目录错误、权限、代理与证书、版本不兼容、全局与本地混淆是五类常见失败点。处理后使用npm ls确认能列出依赖，再确认npm run命令成功。

先确认终端位于正确项目目录并有package.json，再检查网络、代理、证书和注册表配置。权限错误不应直接用管理员终端长期绕过；先确认目录所有权、缓存位置和公司策略。某个包安装失败时，查看错误中具体包名、Node版本与原生编译信息。

原生扩展可能需要匹配的编译工具、Python或预编译二进制文件。升级Node.js后出现ABI不兼容，应重新安装依赖并按包文档处理，而不是从不明网站下载单独二进制文件。若npm命令本身不可用，转到Node与npm命令排查，先修复运行环境。

建立可复查的项目交付

依赖验证不能只看安装日志。至少执行一次npm ls、运行项目脚本并触发使用该依赖的代码路径。若依赖提供命令行工具，应优先通过项目script调用本地版本，避免开发机上的全局版本掩盖缺失配置。

交付前可以在新的空目录检出代码，使用锁文件重新安装，再执行启动与测试命令。这个动作能发现未提交配置、隐式全局包和错误的文件大小写。对于持续集成环境，应固定Node.js大版本并保存安装日志，升级时再有计划地调整。

本页回答的是初始化Node.js项目、安装本地依赖并通过package.json管理命令。下一步可进入/modules/index.html统一项目的导入导出方式。

提交package.json和锁文件，记录Node.js版本要求与启动命令；在干净目录执行一次依赖安装和测试，确认项目不依赖未记录的全局包。生产安装可根据项目策略使用锁文件对应的确定性命令，并在升级前审查依赖变化。

准备拆分代码时阅读CommonJS与ESM；还没有运行过基础脚本时返回Node.js入门；版本线选择不确定时先看LTS指南。需要安装运行时则进入Node.js下载页。