Node.js模块管理核心：npm、package.json与依赖工作流详解

1. 项目概述：Node.js模块管理的底层逻辑与真实工作流

“Cómo usar módulos Node.js con npm y package.json”——这个西班牙语标题直译是“如何使用 npm 和 package.json 来管理 Node.js 模块”，但它背后承载的，远不止一句操作指南。它是一整套现代 JavaScript 开发者每天都在依赖、却常常只知其然不知其所以然的工程化基础设施。我从 2013 年第一次在 Ubuntu 上敲下npm install express开始，到如今带团队维护数十个跨版本、多环境、含私有 registry 的 Node.js 服务，踩过的坑、改过的配置、重装过的 node_modules 目录，摞起来比《JavaScript 高级程序设计》还厚。这不是一个“安装完就完事”的流程，而是一条贯穿开发、测试、部署、协作全生命周期的隐性链条。

核心关键词Node.js、npm、package.json、módulos（西班牙语“模块”）——它们不是孤立名词，而是彼此咬合的齿轮：Node.js 是运行时引擎，npm 是包管理器兼构建脚本调度器，package.json 是整个项目的元数据契约，而 módulos 则是可复用、可组合、可版本锁定的代码单元。你看到的是require('lodash')或import { debounce } from 'lodash'，但背后是 npm 解析语义化版本、校验 integrity 哈希、构建符号链接、处理 peerDependencies 冲突、甚至动态 patch 依赖树的一整套精密机制。那些热搜词里反复出现的npm : 无法加载文件 ... npm.ps1，因为在此系统上禁止运行脚本、could not read package.json: ENOENT、npm WARN unknown project config "shamefully-hoist"，都不是偶然报错，而是这套机制在 Windows 权限模型、缺失初始化文件、或过时配置项等边界条件下发出的真实警报。它们指向的，是开发者对这套系统理解的断层：我们习惯于复制粘贴npm init -y，却很少思考-y跳过了哪些关键决策；我们熟练输入npm install --save-dev jest，却不清楚--save-dev在现代 npm（v7+）中已被默认行为取代，而devDependencies字段的真正意义在于“仅用于本地开发构建，不参与生产打包”。

这篇文章写给三类人：一是刚装好 Node.js、面对终端黑窗口手足无措的新手，你需要知道package.json不是可选配置，而是项目存在的“身份证”；二是能跑通npm start却总在 CI/CD 流水线里卡在npm ci报错的中级开发者，你需要理解package-lock.json如何成为可重现构建的唯一真相；三是负责技术选型、要评估 pnpm/yarn 与 npm 差异的团队骨干，你需要看清node_modules结构差异背后，是对磁盘空间、安装速度、以及hoisting（提升）行为安全性的根本权衡。全文不讲抽象理论，只拆解真实命令背后的执行路径、参数取舍的工程依据、以及那些官方文档里不会明说的“潜规则”。比如，为什么npm install默认会修改package.json？为什么npm ci必须要求package-lock.json存在且完整？为什么把npm全局路径改成 D 盘后，npx却突然找不到本地安装的工具？这些，才是你每天和 Node.js 打交道时，真正需要握在手里的“扳手”。

2. 核心设计思路：npm 为何选择 package.json 作为单一事实源

2.1 package.json 不是配置文件，而是项目契约书

很多新手误以为package.json是一个类似.gitignore的纯配置文件，可以随意增删字段。这是最危险的认知偏差。package.json是 Node.js 生态的“宪法性文件”——它定义了项目身份（name,version）、作者信息（author,license）、入口点（main,types,exports）、脚本指令（scripts）、依赖关系（dependencies,devDependencies,peerDependencies）以及构建约束（engines,os,cpu）。npm 的所有核心操作，都围绕解析、验证、更新这份契约展开。

举个具体例子：当你执行npm install axios，npm 并非简单地下载代码。它首先读取当前目录下的package.json，检查dependencies字段是否存在axios条目；若不存在，则根据engines.node字段（如"node": ">=18.0.0"）判断当前 Node.js 版本是否兼容；接着查询registry（默认为 https://registry.npmjs.org/），获取axios最新稳定版（如1.7.2）的dist.tarball下载地址；下载后，npm 会计算 tarball 的integrity哈希值（如sha512-...），并将其写入package-lock.json；最后，npm 修改package.json的dependencies字段，添加"axios": "^1.7.2"，并同步更新package-lock.json中axios及其所有子依赖的精确版本与哈希。这一连串动作，确保了package.json始终记录“我声明需要什么”，而package-lock.json则记录“我实际安装了什么”。这种分离设计，是 npm 区别于早期npm install无锁机制的核心进化。

提示：package-lock.json文件绝不能被.gitignore忽略。它是实现“同一份package.json，在任何机器上npm ci安装出完全一致的node_modules”的唯一保障。忽略它，等于放弃可重现构建。

2.2 npm 与 pnpm/yarn 的根本分歧：node_modules 结构哲学

热搜词中频繁出现the "pnpm" field in package.json is no longer read by pnpm，这揭示了一个关键事实：不同包管理器对package.json的扩展字段支持，反映了其底层架构的根本差异。npm 使用扁平化node_modules（v3+ 后），通过符号链接将所有依赖提升到顶层node_modules，再由解析算法解决版本冲突；pnpm 则采用硬链接 + 符号链接的“内容寻址存储”（CAS）模式，每个包只在全局 store 中存一份，node_modules里只有指向 store 的符号链接；yarn v1 也用扁平化，但 v2+（Berry）则彻底抛弃node_modules，改用.yarn/cache和.pnp.cjs运行时钩子。

这种差异直接导致package.json字段的语义变化。例如，pnpm曾支持"pnpm": { "peerDependencyRules": { "ignore": ["webpack"] } }字段，用于覆盖严格的 peerDependencies 检查。但当 pnpm 自身不再读取该字段时，意味着它已将策略控制权移交给了更底层的pnpmfile.cjs钩子脚本。这并非功能倒退，而是架构演进：将配置逻辑从声明式 JSON 移向可编程的 JavaScript，赋予用户对安装过程的完全控制力。相比之下，npm 的package.json字段（如"resolutions"）仍停留在声明式层面，灵活性受限。因此，选择哪个包管理器，本质是选择一种工程哲学：你更信任标准化的、开箱即用的扁平化方案（npm），还是愿意为极致的磁盘节省与安装速度，付出学习 CAS 模型与编写钩子脚本的成本（pnpm）？

2.3 scripts 字段：被严重低估的自动化中枢

package.json中的"scripts"字段，常被简化为start、test、build三个按钮。但它的威力远超于此。scripts是 npm 内置的、零依赖的跨平台任务运行器。npm run dev实际执行的是cross-env NODE_ENV=development nodemon server.js，其中cross-env是一个独立的 npm 包，而nodemon是另一个。npm 会自动将node_modules/.bin加入临时 PATH，使得所有本地安装的 CLI 工具（如jest,eslint,tsc）无需全局安装即可在脚本中直接调用。

更深层的价值在于链式编排。你可以定义：

"scripts": { "prebuild": "npm run lint && npm run clean", "build": "tsc && webpack --mode production", "postbuild": "echo 'Build completed at $(date)'" }

这里的prebuild和postbuild是 npm 的生命周期钩子，会在build执行前后自动触发。这种声明式编排，避免了引入 Gulp 或 Grunt 等额外构建工具的复杂性。而热搜词中npm should be run outside of the node.js repl, in your normal shell.正是源于此：Node.js REPL 是一个交互式 JavaScript 解释器，它没有npm的 PATH 注入、没有生命周期钩子解析、也没有node_modules/.bin的自动发现能力。所有scripts必须在系统 shell（如 PowerShell、bash、zsh）中执行，这是设计使然，而非 bug。

3. 核心实操要点：从零初始化到依赖管理的完整闭环

3.1 初始化项目：npm init的三种姿态与隐藏选项

创建一个新项目，第一步永远是生成package.json。npm init提供了三种典型路径，每种对应不同的成熟度与控制粒度：

1. npm init -y（或npm init --yes）：这是新手最常用的“一键生成”。它跳过所有交互式提问，使用默认值创建package.json：name为当前目录名，version为1.0.0，description为空，main为index.js，license为ISC。优点是快，缺点是丢失了关键决策点。例如，main字段默认index.js，但如果你的项目是 TypeScript，真正的入口应是dist/index.js，types字段应指向dist/index.d.ts。-y模式下，这些都需要手动修改。

2. npm init（无参数）：进入交互式向导。它会逐项询问package name、version、description、entry point、test command、git repository、keywords、author、license。这是推荐给所有人的标准流程。尤其注意entry point：对于库（library）项目，它应是编译后的 JS 文件；对于应用（application）项目，它可以是启动脚本（如server.js）。test command则决定了npm test的行为，应提前规划好测试框架（Jest/Mocha）。

3. npm init <initializer>（初始化器）：这是高级用法，利用社区模板快速搭建项目骨架。例如npm init vite@latest创建 Vite 项目，npm init @eslint/config交互式配置 ESLint。它本质上是执行一个名为create-<initializer>的 npm 包（如create-vite），该包会生成预设的package.json、配置文件及源码结构。这极大提升了工程一致性，但需警惕模板的版本陈旧问题——一个基于 Vue 2 的create-vue模板，可能无法适配 Vue 3 的 Composition API。

注意：npm init生成的package.json中，"private": true字段常被忽略。若你的项目是内部服务或未打算发布到 npm registry，务必手动添加此字段。它能防止意外执行npm publish，避免私有代码泄露。

3.2 依赖分类：dependencies、devDependencies 与 peerDependencies 的实战边界

package.json中的依赖字段，是项目健康度的晴雨表。错误分类不仅浪费安装时间，更会引发运行时错误。

• dependencies：项目运行时必需的包。例如express（Web 框架）、mysql2（数据库驱动）、lodash（工具函数库）。它们会被npm install（无参数）默认安装，并出现在node_modules中。npm install <pkg>命令等价于npm install <pkg> --save（v5+ 后--save已默认）。

• devDependencies：仅在开发与构建阶段需要的包。例如jest（测试框架）、typescript（编译器）、eslint（代码检查）、webpack（打包工具）。它们不会被npm install --production安装，从而减小生产环境体积。npm install <pkg> --save-dev或简写npm install <pkg> -D将包添加至此字段。

• peerDependencies：这是一个契约性声明，表示“我的包期望宿主环境提供某个特定版本的包”。它常见于插件（plugin）或 UI 组件库。例如eslint-plugin-react的peerDependencies会声明"eslint": "^8.0.0"，意思是：“我需要宿主项目已安装 ESLint v8.x，否则我无法正常工作”。npm v7+ 会在npm install时自动检查并警告缺失的 peerDependencies，但不会自动安装它们。这是为了防止版本冲突——宿主项目应自行决定安装哪个版本的eslint。

一个经典反例是vue和vue-template-compiler。在 Vue 2 项目中，vue-template-compiler必须与vue主包严格同版本（如都是2.6.12）。若将vue-template-compiler错误地放入dependencies，而vue在devDependencies，则npm install --production会只安装vue-template-compiler，导致生产环境缺少vue运行时，应用崩溃。正确做法是：vue放dependencies，vue-template-compiler放devDependencies，并确保两者版本号完全一致。

3.3 安装与更新：npm install、npm update与npm ci的精准用法

这三个命令看似相似，实则服务于完全不同的场景：

• npm install（无参数）：这是日常开发的主力命令。它会：

  1. 读取package.json，确定所需依赖。
  2. 读取package-lock.json，检查是否有已锁定的精确版本。
  3. 若package-lock.json存在且完整，则按锁文件安装，保证一致性。
  4. 若package-lock.json不存在或不完整，则根据package.json中的语义化版本范围（如^1.7.2）解析最新兼容版本，安装并生成/更新package-lock.json。关键点：npm install会修改package-lock.json，并可能修改package.json（当使用--save或--save-dev时）。

• npm update：用于升级现有依赖到满足语义化版本范围的最新版。例如，package.json中"lodash": "^4.17.21"，当前node_modules中是4.17.21，而 registry 中已有4.17.25，则npm update lodash会将其升级到4.17.25，并更新package-lock.json。它不会升级到5.0.0，因为^规则只允许补丁和次版本升级。npm update不会安装新包，只更新已存在包的版本。

• npm ci（Clean Install）：这是 CI/CD 流水线和生产部署的黄金标准。它要求：

  1. package-lock.json必须存在且完整（所有依赖及其子依赖的integrity哈希必须存在）。
  2. node_modules目录必须不存在（或先被清除）。
  3. npm ci会完全忽略package.json中的版本范围，只严格按照package-lock.json中记录的精确版本和哈希进行安装。它不会生成新的package-lock.json，也不会修改package.json。结果：npm ci的安装速度通常比npm install快 2-3 倍，且 100% 可重现。这也是为什么npm ci是 Jenkins/GitLab CI 的首选命令。

实操心得：在团队协作中，应约定package-lock.json必须提交到 Git。若某次npm install后package-lock.json发生大量变更（尤其是integrity字段），不要直接提交，先执行npm ci清理环境，再重新npm install，确保锁文件变更仅反映真实的依赖更新。

4. 实操过程详解：解决高频报错与环境配置陷阱

4.1 Windows 权限报错：npm.ps1 cannot be loaded because running scripts is disabled

这是 Windows PowerShell 用户最常遇到的拦路虎，报错信息如npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。根源在于 PowerShell 的执行策略（Execution Policy）默认为Restricted，禁止运行任何本地脚本，包括 npm 封装的npm.ps1。

解决方案分三步，按推荐顺序排列：

1. 首选：切换到 CMD 或 Git Bash
   PowerShell 的限制是其安全特性，绕过它并非最佳实践。npm的核心功能在 CMD（命令提示符）和 Git Bash（基于 MinTTY）中完全可用，且无此限制。在 VS Code 中，可通过终端右上角的+号切换终端类型。这是最安全、最无副作用的方案。

2. 次选：为当前用户设置执行策略（推荐）
   若必须使用 PowerShell，执行以下命令（以管理员身份打开 PowerShell）：

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

   RemoteSigned策略允许运行本地脚本（如npm.ps1），但要求从互联网下载的脚本必须有可信证书签名。-Scope CurrentUser仅影响当前登录用户，不影响系统其他用户，安全性可控。

3. 不推荐：禁用执行策略（高风险）
   Set-ExecutionPolicy Unrestricted -Scope CurrentUser会允许所有脚本运行，包括恶意脚本，强烈不建议。

注意：npm命令本身是一个.cmd文件（位于nodejs\目录下），它会调用npm.ps1。因此，即使你设置了npm的别名或修改了 PATH，只要最终调用链涉及.ps1，就仍会触发此错误。坚持使用 CMD/Git Bash 是最省心的选择。

4.2package.json缺失与损坏：could not read package.json: ENOENT

ENOENT: no such file or directory, open 'xxx\package.json'表明 npm 在当前工作目录找不到package.json。这通常发生在两种场景：

• 场景一：在错误目录执行命令
  你在一个空文件夹或项目根目录的子文件夹（如src/）中执行了npm install。解决方法很简单：使用cd ..返回上一级，或cd /d D:\my-project切换到正确的项目根目录，确保该目录下存在package.json。

• 场景二：package.json文件被意外删除或损坏
  如果文件存在但内容为空或格式错误（如 JSON 语法错误），npm 也会报ENOENT或更具体的SyntaxError。此时，可尝试：

  1. 用文本编辑器（如 VS Code）打开package.json，检查是否为合法 JSON（所有键名和字符串必须用双引号，末尾不能有多余逗号）。
  2. 若文件完全空白，且你记得项目基本信息，可手动重建一个最小package.json：

  { "name": "my-project", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }

  3. 若你有 Git 历史，直接执行git checkout -- package.json恢复。

提示：npm init是package.json的终极保险。即使文件损坏，只要在项目根目录运行npm init -y，它会生成一个全新的、格式正确的package.json，覆盖旧文件。这是比手动修复更快捷的方法。

4.3 全局路径配置：npm install -g安装失败与npx失效

npm install -g默认将全局包安装到C:\Users\<username>\AppData\Roaming\npm（Windows）或/usr/local/bin（macOS/Linux）。但许多用户会因磁盘空间或权限问题，将全局路径修改为 D 盘或其他位置。常见错误配置是只修改了prefix，却忽略了cache。

正确配置步骤：

1. 创建新目录：在 D 盘创建两个文件夹，例如D:\npm-global和D:\npm-cache。
2. 配置 npm：

   npm config set prefix "D:\npm-global" npm config set cache "D:\npm-cache"

3. 更新系统 PATH：将D:\npm-global添加到系统环境变量PATH中（Windows：系统属性 -> 高级 -> 环境变量 -> 系统变量 -> Path -> 新建；macOS/Linux：在~/.bashrc或~/.zshrc中添加export PATH="D:\npm-global:$PATH"）。
4. 重启终端：使 PATH 变更生效。

为什么npx会失效？
npx的工作原理是：先检查本地node_modules/.bin，再检查全局prefix目录下的node_modules/.bin。如果prefix配置错误，npx就找不到全局安装的命令。例如，你执行npm install -g create-react-app，但npx create-react-app my-app报错'create-react-app' 不是内部或外部命令，大概率就是prefix未正确加入 PATH。

实操心得：配置完成后，执行npm config list查看所有配置，确认prefix和cache路径正确无误。然后执行npm list -g --depth=0，应能列出所有全局安装的包。最后，执行npx -v，若返回版本号，则npx已正常工作。

5. 常见问题与排查技巧实录：来自生产环境的 7 个真实案例

5.1 案例一：npm install后node_modules为空，无任何报错

现象：执行npm install后，终端显示added 123 packages，但打开node_modules文件夹，里面空空如也。

排查思路：

• 第一步：检查package.json中的name字段。如果name与当前目录名完全相同，npm 会认为这是一个“本地链接包”，并跳过安装，直接创建一个指向当前目录的符号链接。这是 npm 的一个古老特性，用于本地开发调试。
• 第二步：执行npm ls，查看依赖树。如果输出my-project@1.0.0后直接结束，没有子节点，基本可确认是name冲突。
• 解决方案：修改package.json中的name字段，使其与目录名不同（如加前缀my-或后缀-app），然后删除node_modules和package-lock.json，重新执行npm install。

5.2 案例二：npm start报错command not found: cross-env

现象：package.json中"scripts": { "start": "cross-env NODE_ENV=development node server.js" }，但执行npm start时提示cross-env: command not found。

原因分析：cross-env被安装在了devDependencies，而npm start是一个scripts命令，它会自动将node_modules/.bin加入 PATH。理论上，cross-env应该能被找到。问题往往出在：

• node_modules目录未正确生成（见案例一）。
• cross-env未被正确安装，可能是因为网络问题导致安装中断。
• 当前终端缓存了旧的 PATH，未刷新。

解决方案：

1. 执行ls node_modules/.bin | grep cross-env（macOS/Linux）或dir node_modules\.bin\cross-env*（Windows），确认cross-env可执行文件是否存在。
2. 若不存在，执行npm install cross-env --save-dev。
3. 若存在，关闭当前终端，重新打开，再试npm start。

5.3 案例三：npm install卡在fetchMetadata，长时间无响应

现象：npm install执行后，卡在fetchMetadata: sill fetchPackageMetaData error for xxx，数分钟无进展。

根本原因：npm 默认 registry（https://registry.npmjs.org/）在国内访问缓慢或不稳定。这是中国开发者最普遍的痛点。

国内镜像解决方案：

• 临时切换：npm install axios --registry https://registry.npmmirror.com
• 永久切换（推荐）：

  npm config set registry https://registry.npmmirror.com # 验证 npm config get registry

  https://registry.npmmirror.com（原淘宝镜像）是目前最稳定、同步最快的国内源。

注意：npm install时若指定了--registry参数，它会覆盖config中的设置，优先级更高。

5.4 案例四：npm install后，require('some-module')报错Cannot find module

现象：模块已成功安装，node_modules中存在该模块文件夹，但require('some-module')仍报错。

深度排查：

• 检查模块入口：some-module的package.json中main字段指向的文件是否存在？例如，main: "lib/index.js"，但lib/目录下没有index.js，只有index.cjs。
• 检查 Node.js 版本兼容性：some-module的engines.node字段（如"node": ">=16.0.0"）是否与你当前node -v版本匹配？不匹配时，npm 可能会静默跳过某些文件。
• 检查exports字段：现代模块（如lodash-es）使用exports字段定义不同环境的入口。require()是 CommonJS 方式，若exports中未定义.的require入口，则会失败。此时应改用import。

5.5 案例五：npm install安装了错误的版本，如node.js v24.16.0 is not yet released

现象：执行npm install时，终端输出error installing 24.16.0: node.js v24.16.0 is not yet released or is not available.

原因：这不是 npm 的错，而是你项目package.json中的engines.node字段写错了。例如，你写了"node": "24.16.0"，但 Node.js 官方尚未发布此版本（Node.js 版本号是MAJOR.MINOR.PATCH，如20.12.0，24.16.0是无效的）。npm 在安装依赖前，会检查engines约束，发现不匹配就报错。

解决方案：打开package.json，将engines.node修改为一个真实存在的、且你本地已安装的版本，例如"node": ">=18.0.0"或"node": "20.12.0"。然后重新npm install。

5.6 案例六：npm install后，npm run build报错Cannot find module 'typescript'

现象：typescript明明在devDependencies中，node_modules里也有typescript文件夹，但npm run build（脚本中调用tsc）却找不到。

核心原因：npm run脚本执行时，node_modules/.bin被加入 PATH，但tsc是一个 TypeScript 编译器，它需要typescript包本身来运行。如果typescript是devDependencies，它会被正确安装。但如果package.json中scripts.build写成了tsc --build，而tsc命令本身是由typescript包提供的，那么问题可能出在：

• typescript的bin字段未正确注册。检查node_modules/typescript/package.json，确认"bin": { "tsc": "./bin/tsc" }存在。
• 更常见的原因是：tsc命令被系统 PATH 中的全局 TypeScript 覆盖，而全局版本与本地devDependencies版本不兼容。

解决方案：在scripts.build中，显式调用本地tsc：

"scripts": { "build": "npx tsc --build" }

npx会优先查找本地node_modules/.bin/tsc，确保使用的是devDependencies中指定的版本。

5.7 案例七：npm install后，npm outdated显示大量包可更新，但npm update无效果

现象：npm outdated列出lodash,axios等包有新版本，但npm update lodash执行后，package.json和package-lock.json均无变化。

原因：npm update只会将包升级到满足当前package.json中语义化版本范围的最新版。例如，package.json中"lodash": "4.17.21"（无^或~），这是一个精确版本锁定，npm update认为当前版本已是“最新”，不会做任何事。只有"lodash": "^4.17.21"（允许次版本和补丁升级）或"lodash": "~4.17.21"（只允许补丁升级）时，npm update才会生效。

解决方案：

• 若要让npm update生效，需先修改package.json，将精确版本改为语义化版本，如"lodash": "^4.17.21"。
• 若要强制升级到最新主版本（如5.0.0），必须使用npm install lodash@latest，这会覆盖package.json中的版本号。

总结：npm outdated是一个“扫描仪”，npm update是一个“保守升级器”，而npm install <pkg>@latest是一个“激进更新器”。三者各司其职，混用会导致混乱。

6. 进阶实践：package.json 的隐藏字段与未来趋势

6.1exports字段：现代模块系统的基石

exports字段是 Node.js v12.20.0+ 引入的，用于精确控制模块的入口点，是替代main和module字段的现代方案。它解决了main（CommonJS）与module（ESM）并存时的歧义问题。

一个典型的exports配置如下：

{ "exports": { ".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs", "default": "./dist/index.mjs" }, "./package.json": "./package.json", "./utils/*": "./dist/utils/*.js" } }

• "."表示模块的根入口。
• "import"指定 ESM（import）方式导入时的文件。
• "require"指定 CommonJS（require）方式导入时的文件。
• "default"是兜底入口，当其他条件不匹配时使用。
• "./utils/*"是子路径导出，允许用户import { helper } from 'my-lib/utils/helper'。

为什么重要？
如果你的库同时支持 ESM 和 CommonJS，exports是唯一能确保用户无论用import还是require都能获得正确格式代码的方案。main字段在 ESM 环境下会被忽略，而module字段又非官方标准，exports则是 Node.js 官方推荐的、未来的唯一标准。

6.2type字段：决定整个项目的模块系统

package.json中的"type": "module"是一个全局开关，它告诉 Node.js：本项目中的所有.js文件，默认按 ESM（ECMAScript Module）规范解析。这意味着：

• import/export语法可以直接使用。
• require()语法将不可用（除非使用createRequire）。
• __dirname和__filename将不可用（需用import.meta.url）。

反之，"type": "commonjs"（默认值）则让所有.js文件按 CommonJS 规范解析。

最佳实践：新项目应统一模块系统。若选择 ESM，务必在package.json中明确设置"type": "module"，并确保所有依赖也支持 ESM。混合使用（如type: module但require一个 CJS 包）会导致运行时错误。

6.3pnpm字段的消亡与pnpmfile.cjs的崛起

热搜词中 `the "pnpm" field in package