package.json 中 dependencies 的版本号：它真的是版本号吗？

在 Node.js 或前端项目中，package.json 是项目依赖管理的核心文件。我们常常在 dependencies、devDependencies、peerDependencies 等字段中指定每个依赖的"版本号"。然而，这些"版本号"并不总是真正的版本号，它们还可以是本地路径、Git 地址、文件系统地址，甚至是通配符等。本文将全面介绍这些用法及其含义，并通过示例加深理解。

一、常规版本号语法

在介绍一些你可能不熟悉的用法前，让我们先回顾一下你所熟悉的用法。

1. 精确版本

"lodash": "4.17.21"

表示只能安装 4.17.21 版本，不能有任何波动。

2. 范围版本

^：兼容主版本

"lodash": "^4.17.0"

表示安装 >=4.17.0 <5.0.0 的版本。常用于库依赖，确保 API 向后兼容。

~：兼容小版本

"lodash": "~4.17.0"

表示安装 >=4.17.0 <4.18.0 的版本。适用于只允许 patch 更新的情况。

区间范围

"lodash": ">=4.17.0 <5.0.0"

明确指定版本范围，更加灵活。

二、非常规版本号语法

下面让我们来瞧一瞧一些非常规的版本号。

1. 星号 *

"lodash": "*"

表示任意版本都可以安装。这种用法在生产环境中风险较高，容易引入不兼容版本，通常只在快速原型或测试中使用。在使用monorepo的时候， * 还有一些特殊的用处，将在 第八节 中进行介绍。

2. 最新版本标签（例如 latest、beta）

json
"some-lib": "latest"
"some-lib": "next"
"some-lib": "beta"

这些是 NPM 的 dist-tag，会安装对应 tag 指向的版本。例如 latest 通常是当前稳定版。

三、本地路径引用

在本地开发多个包时联调，这种用法非常有用，可以让包管理工具从本地文件夹安装依赖。

1. file: 协议

json
复制编辑
"my-lib": "file:../my-local-lib"

表示从本地文件夹安装依赖。你也可以指定 .tgz 包文件：

"my-lib": "file:./libs/my-lib-1.0.0.tgz"

2. 省略 file: 前缀后的行为分析

有时候，你可能会看到不少人在使用file: 协议的时候，省略了 file: 前缀。其实，这种写法是有一些问题的，因为它的行为取决于你使用的包管理器（npm、yarn、pnpm）以及路径的格式。

✅ 可以省略 file: 的情况（部分工具 & 格式）

某些情况下，比如你写的是一个相对路径（不带协议），部分包管理器会自动推断为本地路径，并当作 file: 来处理。

例如：

"my-lib": "../my-lib"

等价于：

"my-lib": "file:../my-lib"

在以下情况下大多数工具都可以正确解析：

• 相对路径：../lib、./lib
• 绝对路径：/Users/xxx/project/lib

🚫 不能省略 file: 的情况

以下情况必须带 file: 前缀：

• 路径为压缩文件（如 .tgz）时，必须加 file:

"my-lib": "file:../my-lib-1.0.0.tgz" ✅
"my-lib": "../my-lib-1.0.0.tgz" ❌（npm 会报错）

• Monorepo 使用 Yarn workspace 时，推荐显式加 file:

虽然 Yarn 可以自动识别 workspace 下的路径，但显式指定 file: 或 workspace: 更清晰且可读性更强。

各工具行为差异总结

场景 / 工具	相对路径是否可以省略 file:	.tgz 是否可以省略 file:	推荐做法
npm	✅ 是（对文件夹）	❌ 否（对文件）	显式写 file: 更稳妥
Yarn Classic	✅ 是	❌ 否	显式写 file: 更清晰
Yarn Berry	✅ 是	❌ 否	更推荐 workspace: 或 file:
pnpm	✅ 是（支持路径 auto 推断）	❌ 否	推荐使用 file:

3. 推荐实践

为了 最大兼容性 和 可读性清晰 ，建议始终显式使用 file:：

"my-lib": "file:../my-lib"

"my-lib": "file:../my-lib-1.0.0.tgz"

四、Monorepo 场景中的 workspace 协议

在使用Monorep的时候，工作区中的package.json（即非根package.json）中可以使用 workspace:*、workspace:^ 、workspace:~，例如：

"my-shared-lib": "workspace:*"

这是 Yarn 和 pnpm 在 Monorepo 项目中支持的特性，用于声明依赖于工作区中其它包。

• workspace:*：匹配任意版本。
• workspace:^1.2.0：等价于 ^1.2.0，但强制来自 workspace 中的包。
• workspace:~1.2.0：与上类似，强制来自 workspace。

注意 ：npm 从 v7 之后也开始支持 workspaces，但不支持 workspace:* 这种语法。

五、Git 仓库引用

1. Git 地址（使用 HTTPS 或 SSH）

"my-lib": "git+https://github.com/username/my-lib.git"

或

"my-lib": "git+ssh://git@github.com:username/my-lib.git"

默认会安装该仓库的 master/main 分支的最新提交。

2. Git 地址 + tag / branch / commit

"my-lib": "git+https://github.com/username/my-lib.git#v1.2.3"
"my-lib": "git+https://github.com/username/my-lib.git#develop"
"my-lib": "git+https://github.com/username/my-lib.git#6db6f8a"

• #v1.2.3：指定 tag
• #develop：指定分支
• #commit-hash：指定具体 commit

六、URL（HTTP 资源）

"my-lib": "https://example.com/path/to/my-lib.tgz"

可以直接从远程地址下载 .tgz 包。这种方式不常见，适用于自建仓库或发布测试包。

七、其他不常见用法

GitHub 缩写（npm 特有语法）

"my-lib": "username/my-lib"

等价于：

"my-lib": "git+https://github.com/username/my-lib.git"

还可以加上 tag：

"my-lib": "username/my-lib#v1.0.0"

八、混用情况分析：版本冲突怎么处理？

以 Monorepo 中为例：

// 根 package.json
"lodash": "^4.17.0"

// 工作区中某个子包的 package.json
"lodash": "*"

在这种情况下，具体安装哪个版本由依赖管理工具（Yarn、PNPM、npm）决定：

• Yarn Berry/PNPM（hoist=false） 会使用子包中的声明版本（也可能安装多个版本）
• NPM/Yarn classic（hoist=true） 优先使用根目录中的版本（如果符合子包声明）

所以建议统一声明版本，或在子包中使用 workspace:* 强制引用根版本。

九、总结

类型	示例	说明
精确版本	"lodash": "4.17.21"	只安装指定版本
版本范围	"lodash": "^4.17.0"	安装范围内最新版本
任意版本	"lodash": "*"	安装任意版本（不推荐）
dist-tag	"my-lib": "latest"	安装发布标签对应版本
本地文件夹	"my-lib": "file:../my-lib"	引用本地包
本地 tar 包	"my-lib": "file:./lib.tgz"	本地 tgz 文件
Git 仓库	"my-lib": "git+https://github.com/u/lib.git"	从 Git 拉取
Git + tag/commit	"my-lib": "git+https://...#v1.0.0"	指定 tag 或提交
URL 下载	"my-lib": "https://example.com/lib.tgz"	HTTP 下载
workspace 协议	"my-lib": "workspace:*"	Monorepo 工作区依赖

十、推荐实践

• 生产环境中避免使用 * 或 latest，防止出现意料之外的版本升级。
• Monorepo 中尽量使用 workspace: ，确保一致性与版本对齐。
• 本地开发联调建议使用 file: ，快速迭代。
• 使用 ^ 和 ~ 时要结合语义化版本管理（SemVer）策略，避免不兼容变更。