NPM 你需要知道的

September 10, 2024 5 分钟阅读时间

npm vs pnpm

什么是幽灵依赖？

幽灵依赖（Ghost Dependencies） 是指项目中使用了未在 package.json 中明确声明的依赖。这种情况通常发生在 npm 和 Yarn 中，因为它们的扁平化依赖结构允许访问未直接声明的包。

示例

假设你的项目直接依赖 express：

{
  "dependencies": {
    "express": "4.17.1"
  }
}

express 依赖于 body-parser，因此 body-parser 也会被安装到 node_modules 中。

在你的代码中，你可以直接使用 body-parser，尽管没有在 package.json 中声明它：

const bodyParser = require('body-parser');

这段代码能够运行，但 body-parser 实际上是一个 幽灵依赖。

存在的问题

可靠性问题
如果未来 express 不再依赖 body-parser，你的代码可能会突然崩溃。
版本不一致
不同的开发者可能安装不同版本的依赖，导致项目行为不一致。
维护困难
幽灵依赖让项目的依赖关系变得模糊，增加了维护成本。

pnpm 解决的问题

pnpm 通过严格的依赖树结构和优化的存储机制，解决了传统包管理工具（如 npm 和 Yarn）中的许多问题，包括幽灵依赖问题。

1. 磁盘空间效率

特点：pnpm 使用硬链接和符号链接来共享包，避免重复安装相同的包。
解决的问题：减少了磁盘空间的使用，尤其是在大型项目中效果显著。

2. 安装速度

特点：pnpm 通常比 npm 更快，特别是在安装大型项目依赖时。
解决的问题：加快了项目的初始设置和依赖更新过程，提高了开发效率。

3. 依赖管理

特点：pnpm 使用严格的依赖树结构，只允许访问明确声明的依赖。
解决的问题：消除了“幽灵依赖”问题，提高了项目的可靠性和可维护性。

4. 单一存储

特点：pnpm 在系统中维护一个集中的包存储（全局存储），所有项目共享这些包。
解决的问题：进一步节省磁盘空间，同时加快了多个项目的包安装速度。

5. 并行安装

特点：pnpm 默认并行安装包，充分利用多核 CPU 的性能。
解决的问题：减少了大型项目的依赖安装时间，提升了安装效率。

6. 更好的锁文件

特点：pnpm 的锁文件（pnpm-lock.yaml）更加简洁且易于版本控制。
解决的问题：改善了团队协作和版本一致性，确保不同环境下的依赖安装结果一致。

组件库TS类型定义

组件导出声明

示例：组件导出

在组件库中，通常需要为每个组件提供默认导出和类型定义。例如：

// Button/index.ts
export { default as Button } from './Button';
export type { ButtonProps } from './Button';

`package.json` 的 `exports` 字段

为了支持 CommonJS 和 ESM 模块系统，同时提供类型定义文件，可以在 package.json 中使用 exports 字段进行细粒度的模块导出配置。

{
  "name": "my-component-library",
  "version": "1.0.0",
  "main": "cjs/index.js", // CommonJS 入口
  "module": "esm/index.js", // ESM 入口
  "types": "esm/types/index.d.ts", // 主入口的类型定义文件
  "exports": {
    "./button": {
      "require": "./cjs/Button/index.js", // CommonJS 导入路径
      "import": "./esm/Button/index.js", // ESM 导入路径
      "types": "./esm/types/Button/index.d.ts" // Button 组件的类型定义
    },
    "./modal": {
      "require": "./cjs/Modal/index.js", // CommonJS 导入路径
      "import": "./dist/Modal/index.js", // ESM 导入路径
      "types": "./cjs/types/Modal/index.d.ts" // Modal 组件的类型定义
    }
  }
}

TypeScript 配置 (`tsconfig.json`)

为了确保 TypeScript 能正确解析模块并生成类型定义文件，需要对 tsconfig.json 进行适当配置。

示例配置

{
  "compilerOptions": {
    "moduleResolution": "node16", // 支持 Node.js 16+ 的 ESM 模块解析方式
    "declaration": true, // 开启类型定义文件生成
    "declarationDir": "./esm/types", // 类型定义文件的输出目录
    "outDir": "./dist", // 编译输出的目录
    "target": "ESNext", // 目标 ECMAScript 版本
    "module": "ESNext", // 使用 ES 模块
    "strict": true // 启用严格模式
  }
}

重启 TypeScript 服务器

修改 tsconfig.json 后，建议重启 TypeScript 服务器以确保配置生效：

打开 VSCode 命令面板（Ctrl + Shift + P 或 Cmd + Shift + P）。
输入 TypeScript: Restart TS Server 并按下回车。

根据 TypeScript 版本提供类型定义

为了兼容不同版本的 TypeScript，可以使用 typesVersions 字段为不同的 TypeScript 版本指定对应的类型定义文件。

示例配置

{
  "name": "my-library",
  "version": "1.0.0",
  "main": "dist/cjs/index.js", // CommonJS 入口
  "module": "dist/esm/index.js", // ESM 入口
  "types": "dist/cjs/index.d.ts", // 默认类型定义文件
  "exports": {
    ".": {
      "require": "./dist/cjs/index.js", // CommonJS 导入路径
      "import": "./dist/esm/index.js" // ESM 导入路径
    }
  },
  "typesVersions": {
    "<4.5": { // 针对 TypeScript < 4.5 的类型定义
      "*": ["dist/cjs/index.d.ts"]
    },
    ">=4.5": { // 针对 TypeScript >= 4.5 的类型定义
      "*": ["dist/esm/index.d.ts"]
    }
  }
}

说明

<4.5：针对较低版本的 TypeScript，使用 CommonJS 类型定义文件。
>=4.5：针对 TypeScript 4.5 及更高版本，使用 ESM 类型定义文件。

UNPKG

UNPKG 是一个基于 npm 的内容分发网络（CDN），允许开发者通过浏览器直接访问和加载 npm 包中的资源。它为前端开发提供了便捷的方式，无需下载或安装即可快速引入所需的库或工具。

UNPKG的核心功能

直接访问 npm 包
UNPKG 提供了一个简单的方式，让开发者可以直接通过 URL 访问 npm 上发布的任何包。
支持版本管理
可以指定加载某个 npm 包的具体版本，确保项目使用的依赖版本稳定且一致。
实时浏览包内容
UNPKG 提供了对 npm 包内容的在线浏览功能，方便开发者查看包的结构和文件内容。
快速加载资源
作为 CDN，UNPKG 利用全球分布式节点加速资源加载，提升页面性能。

如何使用UNPKG

访问库文件

通过 UNPKG，可以直接在 HTML 文件中引入 npm 包中的资源。例如，加载 lodash 库：

<script src="https://unpkg.com/lodash"></script>

上述代码会加载 lodash 的最新版本，并将其挂载到全局变量 _ 中。

加载特定版本的资源

为了避免因版本更新导致的兼容性问题，可以指定加载特定版本的资源。例如，加载 lodash 的 4.17.21 版本：

<script src="https://unpkg.com/[email protected]"></script>

浏览包内容

UNPKG 还支持直接在浏览器中浏览 npm 包的内容。只需访问以下 URL：

https://unpkg.com/<package-name>/

例如，访问 lodash 包的内容：

https://unpkg.com/lodash/

这将显示 lodash 包的目录结构，包括其文件和子目录。

UNPKG的优势

无需安装
开发者可以直接通过 URL 引入所需的库，无需手动下载或安装。
版本控制
支持指定版本号，确保项目使用的依赖版本稳定。
快速加载
借助 CDN 的全球分布式节点，UNPKG 提供了高效的资源加载速度。
透明性
可以直接查看 npm 包的内容，了解其文件结构和依赖关系。
与 npm 生态无缝集成
所有发布到 npm 的包都可以通过 UNPKG 访问，充分利用 npm 的庞大生态系统。

package.json 字段解析

main

main 字段指定了 require 加载包时的默认入口文件。例如，当使用 umd 格式的包时，可以通过 main 指定入口文件。

{
  "main": "dist/my-package.umd.js"
}

exports

exports 字段可以限制外部对包内模块的访问方式。例如：

{
  "exports": {
    ".": "./index.js",
    "./feature": "./feature.js"
  }
}

通过 exports，可以明确指定哪些模块可以被外部访问，从而增强包的安全性和可控性。它可以定义多个文件导出声明。

exports的优先级比main更高，具体查看文档

sideEffects

sideEffects 字段用于标识哪些文件或模块具有副作用（副作用指对外部有影响）。

sideEffects: false 表示所有文件都没有副作用。
sideEffects: ["*.css"] 表示 CSS 文件具有副作用。

{
  "sideEffects": {
    "es/index.js" // 指定入口文件，通常入口文件不能被删除
  }
}

module

module 字段通常用于支持 import/export 语法，指定一个符合 ES Module 规范的模块入口文件。通过区分 main 和 module，可以兼容多种引入方式。

alias

alias 支持 npm 包多版本管理，确保不同版本的依赖能够正确加载。

package-lock.json

package-lock.json 是 npm 的锁文件，用于锁定项目中依赖的具体版本，确保在不同环境中安装的依赖一致。

常见操作

删除 node_modules 后重新运行 npm install 会生成新的 package-lock.json 文件。
使用 npm i 或 npm update 会更新 package-lock.json 文件。

案例分析

案例 1：自动升级导致页面异常

问题描述

由于某个组件库包（如 next）自动升级，导致页面出现异常，例如 setState 引发死循环。而且只有部分用户出现问题，难以定位。

解决方案

通过对比 package-lock.json 文件，发现 next 版本发生了升级。为了避免类似问题：

非必要情况下不要修改 package-lock.json 文件。
如果删除 node_modules 导致某些包版本自动升级，只应调整特定包的版本，而非整体更新。

案例 2：tnpm 配置 resolutions 的问题

问题描述

在使用 tnpm 时，配置了 resolutions 字段后，删除 node_modules 不会自动生成 package-lock.json 文件。

解决方案

将 tnpm 的 resolutions 配置改为 npm 的 overrides 配置，以确保 package-lock.json 文件能够正常生成。

files

在 package.json 中，files 字段用于指定哪些文件或目录会被包含在 npm 打包发布的内容中。通过明确列出需要包含的文件，开发者可以更精确地控制发布的包内容，避免不必要的文件被包含。

官方文档链接

更多信息可以参考 npm 官方文档。

作用与用途

主要功能

控制打包范围：
- files 字段定义了一个文件或目录的白名单，只有列出的文件和目录会被包含在 npm 发布包中。
- 其他未列出的文件（除非是默认包含的文件）将被排除。
减少包体积：
- 通过仅包含必要的文件，可以有效减少 npm 包的体积，提升下载和安装速度。
保护敏感信息：
- 避免意外将测试文件、配置文件或其他非必要内容发布到 npm。

默认行为

即使没有定义 files 字段，npm 也会默认包含以下文件或目录：

package.json
README（支持多种扩展名，如 .md, .txt 等）
CHANGELOG（支持多种扩展名，如 .md, .txt 等）
LICENSE / LICENCE（支持多种扩展名，如 .md, .txt 等）
index.js 或其他入口文件（根据 main 字段定义）

此外，.npmignore 文件会覆盖 files 字段的行为。如果存在 .npmignore，它会进一步过滤掉不需要的文件。

使用方法

基本语法

在 package.json 中，files 是一个数组，每个元素是一个字符串，表示文件路径或目录路径。例如：

{
  "files": [
    "dist/",
    "src/",
    "index.js",
    "README.md"
  ]
}

示例解释

"dist/"：包含整个 dist 目录及其所有子文件。
"src/"：包含整个 src 目录及其所有子文件。
"index.js"：仅包含根目录下的 index.js 文件。
"README.md"：仅包含根目录下的 README.md 文件。

注意事项

优先级规则：
- 如果同时定义了 .npmignore 和 files，files 的优先级更高。
- .gitignore 文件不会影响 files 字段的行为。
排除特定文件：
- 如果需要排除某些文件，可以结合 .npmignore 使用。
- 例如，在 .npmignore 中添加 *.log 可以排除所有日志文件。
调试打包内容：
- 使用以下命令查看实际打包的内容：
```
npm pack
```
- 该命令会生成一个 .tgz 文件，解压后即可查看最终包含的文件。

示例配置

以下是一个完整的 package.json 示例，展示了如何使用 files 字段：

{
  "name": "example-package",
  "version": "1.0.0",
  "description": "An example package demonstrating the use of the 'files' field.",
  "main": "dist/index.js",
  "files": [
    "dist/",
    "src/",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": {
    "typescript": "^4.0.0"
  }
}

删除node_modules

find . -name "node_modules" -type d -prune -print -exec rm -rf "{}" \;

npm link

1. `npm link` 的基本用法

npm link 是一种将本地包链接到项目中的便捷方式，常用于开发和调试。然而，在使用过程中可能会遇到一些问题。

2. 常见问题及解决方案

2.1 删除多余的 `node_modules` 包

问题描述：
- 在执行 npm link 后，可能会出现找不到链接包的情况。
- 这可能是由于 node_modules 中存在多余或不完整的依赖包。
解决方案：
- 检查 node_modules 下的包是否完整。
- 如果存在问题，可以尝试删除多余的 node_modules 并重新安装依赖：
```
rm -rf node_modules package-lock.json
npm install
```
可能原因：
- 不同版本的 npm 可能会导致依赖解析的问题。

2.2 Node.js 版本一致性

问题描述：
- 如果在执行 npm link 前通过 nvm use 14 等命令切换了 Node.js 版本，可能会导致链接的目录结构不一致。
解决方案：
- 确保两个链接的项目使用相同的 Node.js 版本。
- 可以通过以下命令检查和切换版本：
```
nvm list
nvm use <version>
```

2.3 React Hooks 报错问题

问题描述：
- 在使用 npm link 时，可能会遇到以下错误：
```
Hooks can only be called inside the body of a function component.
```
- 原因是项目中存在多个 react 实例（即多个版本的 react 和 react-dom）。

解决方案：

将依赖的 react 和 react-dom 移动到 peerDependencies，确保子项目不会单独安装 react。

链接父项目的 react 和 react-dom，具体步骤如下：

# 1. 在子项目中移除 react 和 react-dom 的直接依赖
npm uninstall react react-dom

# 2. 在子项目的 package.json 中添加 peerDependencies
"peerDependencies": {
  "react": "^17.0.0",
  "react-dom": "^17.0.0"
}

# 3. 链接父项目的 react 和 react-dom
cd PARENT_PROJECT/node_modules/react
npm link
cd ../react-dom
npm link

# 4. 在子项目中链接父项目的 react 和 react-dom
cd CHILD_PROJECT
npm link react
npm link react-dom

1. 快速查看 README

通过命令行快速查看 README 文件内容：

readme net

2. 快速安装 npm 包

使用 npmi 快速安装 npm 包：

npm install -g npmi

3. 说明

readme net：
- 用于快速查看项目的 README 文件内容。
- 确保相关工具已正确安装并配置。
npmi：
- 是一个简化的 npm 安装工具，提升安装效率。
- 安装后可以直接使用 npmi <package-name> 来安装依赖包。
npm version patch
- 自动更新一个新的补丁版本

安装两个不同版本的包

"antdmo2": "npm:antd-mobile@^2.3.4",
"antdmo5": "npm:[email protected]",

References

npm Documentation — Official npm registry and CLI documentation
pnpm Documentation — Official pnpm documentation explaining its advantages over npm
Node.js Package Manager Guide — Socket.dev — Comparison of npm, yarn, and pnpm package managers

npm vs pnpm

什么是幽灵依赖？

示例

存在的问题

pnpm 解决的问题

1. 磁盘空间效率

2. 安装速度

3. 依赖管理

4. 单一存储

5. 并行安装

6. 更好的锁文件

组件库TS类型定义

组件导出声明

示例：组件导出

package.json 的 exports 字段

TypeScript 配置 (tsconfig.json)

示例配置

重启 TypeScript 服务器

根据 TypeScript 版本提供类型定义

示例配置

说明

UNPKG

UNPKG的核心功能

如何使用UNPKG

访问库文件

加载特定版本的资源

浏览包内容

UNPKG的优势

package.json 字段解析

main

exports

sideEffects

module

alias

package-lock.json

常见操作

案例分析

案例 1：自动升级导致页面异常

问题描述

解决方案

案例 2：tnpm 配置 resolutions 的问题

问题描述

解决方案

files

官方文档链接

作用与用途

主要功能

默认行为

使用方法

基本语法

示例解释

注意事项

示例配置

删除node_modules

npm link

1. npm link 的基本用法

2. 常见问题及解决方案

2.1 删除多余的 node_modules 包

2.2 Node.js 版本一致性

2.3 React Hooks 报错问题

1. 快速查看 README

2. 快速安装 npm 包

3. 说明

安装两个不同版本的包

References

Be the first to know when I post cool stuff

`package.json` 的 `exports` 字段

TypeScript 配置 (`tsconfig.json`)

1. `npm link` 的基本用法

2.1 删除多余的 `node_modules` 包