工具-03-包管理器
这篇笔记讲什么
包管理器(package manager)负责自动下载、安装、升级、卸载第三方代码,并解决这些代码之间的依赖关系。这篇笔记讲清三件事:语义化版本(SemVer)与锁文件为什么是工程可靠性的基石;npm / pip / NuGet 三大生态的具体用法;依赖冲突的排查与升级策略。
读完你应该能够:看懂
package.json里每一个字段;解释npm ci与npm install的区别;在一个报「版本冲突」的项目里定位到具体是哪两个包在打架;给新项目定出一份合理的依赖清单。
是什么
包(package) 是可复用的代码分发单元,通常包含代码、元数据(名字、版本、作者、许可证)和依赖声明。包管理器是安装和管理这些包的工具,它同时提供了四样东西:
- 一个仓库(registry):集中存放包的服务器,如 npm registry、PyPI、NuGet.org。
- 一份依赖声明格式:
package.json、pyproject.toml/requirements.txt、.csproj。 - 一个解析器(resolver):读依赖声明,算出一组能同时满足所有约束的版本。
- 一份锁文件(lock file):把解析结果固化下来,保证换台机器装出完全一样的环境。
你的项目声明 解析器 registry 本地磁盘
package.json ──► 版本求解(回溯/贪心) ──► 下载 .tgz/.whl/.nupkg ──► node_modules/
requirements.txt site-packages/
*.csproj ~/.nuget/packages/
│ │
└────────────────► lock 文件(固化解析结果)◄───────────────────────────┘
为什么需要它
依赖地狱:一个真实的最小案例
假设你写了两个库的应用:
- 库 A 依赖 C 的 1.x(
C@1) - 库 B 依赖 C 的 2.x(
C@2)
而 C@2 与 C@1 的 API 不兼容(2.0 删掉了 1.x 的某个函数)。你面临的选择:
| 方案 | 后果 |
|---|---|
只装 C@1 | B 崩(调用了 2.x 才有的接口) |
只装 C@2 | A 崩(调用了已被删除的接口) |
| 两个都装 | 取决于语言:Python 的 import c 只能有一个 c,做不到;Node.js 可以靠嵌套目录共存 |
| 手工把 A 或 B 改成兼容版 | 可能可行,但每次升级都要重做,且你并不拥有这些库 |
这还没算上传递性:A 依赖 C,C 又依赖 D、E、F……依赖树的分支数量随深度指数增长。手工管理到第三层就失控了。
包管理器给出的答案:
| 问题 | 包管理器的机制 |
|---|---|
| 怎么知道要装什么 | 从声明文件(package.json / pyproject.toml / .csproj)读依赖 |
| 怎么挑版本 | 版本约束语法 + 解析器求解 |
| 装到哪 | 项目级隔离(node_modules、虚拟环境、全局包缓存) |
| 怎么保证别人装的一样 | 锁文件 |
| 怎么知道有安全漏洞 | 审计命令(npm audit、pip-audit、dotnet list package --vulnerable) |
| 怎么升级不炸 | 语义化版本 + 测试 + 分批升级策略 |
核心内容
一、语义化版本(Semantic Versioning, SemVer)
版本号形如:
例如 2.14.3、1.0.0-rc.1、3.2.1+build.20261011。
| 位 | 名称 | 何时必须递增 | 对使用者的承诺 |
|---|---|---|---|
| 第一位 | MAJOR(主版本) | 做了不兼容的 API 变更 | 升级要读迁移指南,代码可能报错 |
| 第二位 | MINOR(次版本) | 向后兼容地新增功能 | 可直接升级,旧代码仍能跑 |
| 第三位 | PATCH(修订号) | 向后兼容地修 bug | 应尽快升级,风险最低 |
- 后缀 | 预发布标识 | 非正式版 | 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0 |
+ 后缀 | 构建元数据 | 不影响版本优先级 | 仅作标记,比较时被忽略 |
如何决定升哪一位(这是发布者最容易做错的事):
| 你的改动 | 应升 |
|---|---|
| 删除或重命名公开函数、改参数顺序、改返回类型 | MAJOR |
| 改了默认行为的语义(旧调用结果变了) | MAJOR |
| 提高最低运行时版本要求(如 Node 18 → 20) | MAJOR |
| 新增一个函数、新增一个可选参数 | MINOR |
| 标记某函数为 deprecated(仍可用) | MINOR |
| 修 bug 且不改变公开接口 | PATCH |
| 改文档、改内部实现、补测试 | PATCH(或视情况不发版) |
0.x 版本的特殊性:SemVer 规定 0.y.z 表示「开发中的初始版本,任何东西都可能随时改变」。因此:
0.x阶段 MINOR 位(0.1→0.2)可以包含破坏性变更;- 这也是为什么
^0.2.3只允许到0.3.0之前,而不是像^1.2.3那样允许到2.0.0。 - 实践中:依赖
0.x的包要有心理准备,锁文件和测试是唯一的保护。
版本区间语法对照表(以 npm 的语义为准):
| 写法 | 允许的范围(区间表示) | 说明 | ||
|---|---|---|---|---|
1.2.3 | 精确锁定,不做任何自动升级 | |||
=1.2.3 | 同上,显式写法 | |||
^1.2.3 | 最常用:允许 MINOR 与 PATCH 升级 | |||
^0.2.3 | 0.x 时只允许 PATCH 升级 | |||
^0.0.3 | 0.0.x 时等价于精确锁定 | |||
~1.2.3 | 只允许 PATCH 升级 | |||
~1.2 | 等价于 >=1.2.0 <1.3.0 | |||
~1 | 等价于 1.x | |||
1.2.x | 通配 MINOR 位 | |||
1.x | 通配 MAJOR 位 | |||
* 或 x | 任何版本,不要在生产依赖里用 | |||
>=1.2.3 | 下界限定 | |||
>1.2.3 <2.0.0 | 组合区间,注意是开区间 | |||
1.2.3 - 2.3.4 | 连字符范围,两端都是闭区间 | |||
| `>=1.2.3 <2.0.0 \ | \ | >=3.0.0` | 并集 |
一条实用规则
应用项目用
^(拿到 bug 修复与新特性);库 / 框架本身对依赖用更宽的^、对自己的公开 API 严格遵守 SemVer;对自己发布的包在dependencies里避免写成精确版本,否则下游会被你的选择锁死。
Python 的版本说明符(version specifiers)语法与 npm 略有不同,但语义一致:
| Python 写法 | 含义(区间) |
|---|---|
==1.2.3 | 精确匹配 |
==1.2.* | 前缀匹配 |
~=1.4.2 | 「兼容发布」 |
~=1.4 | 「兼容版本」 |
>=1.2,<2.0 | 组合约束 |
!=1.5.0 | 排除某个已知有问题的版本 |
二、锁文件的意义
问题:package.json 里写的是 "lodash": "^4.17.0"。今天装的是 4.17.21,三个月后新同事装的时候最新版已经是 4.17.30——你们的 node_modules 不一样,但 package.json 一模一样。这就是「在我机器上是好的」的经典来源。
锁文件(lock file) 记录的是解析结果的完整快照:每一个包的确切版本、下载地址、完整性哈希(integrity hash),以及整棵依赖树的形状。
| 生态 | 锁文件 | 是否必须提交到版本控制 |
|---|---|---|
| npm | package-lock.json | 必须 |
| pnpm | pnpm-lock.yaml | 必须 |
| Yarn | yarn.lock | 必须 |
| pip(requirements 方式) | requirements.txt(全部固定) | 必须 |
| Poetry / PDM / uv | poetry.lock / pdm.lock / uv.lock | 必须 |
| NuGet | packages.lock.json(需手动启用) | 推荐(应用项目) |
锁文件保证可复现构建的原理(两个层次):
- 版本可复现:安装时优先按锁文件里的确切版本下载,而不是重新按
^求解。所以 CI、同事、生产服务器装出来的是同一组版本。 - 内容可复现:锁文件里保存了每个包的
integrity哈希(如sha512-...)。下载后校验哈希,不匹配就直接报错。这同时防御了「registry 被入侵替换包内容」这类供应链攻击。
什么情况下锁文件会「失效」
- 有人手动改
package.json的依赖范围并重新install,锁文件被就地更新;- 有人在
.gitignore里把锁文件忽略了(这是反模式);- 用了
npm install <pkg>而不是npm install(会顺带升级其他包);- 合并两个分支时锁文件冲突被随手「解决」成某一方的版本。
正确做法:锁文件的冲突不要手工编辑,应删掉锁文件后重新用声明文件安装一次(
rm package-lock.json && npm install),并跑测试。
# npm ci:面向 CI 的「严格按锁文件安装」
npm ci
| 维度 | npm install | npm ci |
|---|---|---|
| 依赖来源 | package.json(并可能更新锁文件) | 只读 package-lock.json |
| 锁文件不存在时 | 会生成 | 直接报错退出 |
与 package.json 不一致时 | 重新解析并改写锁文件 | 报错退出(这是优点:及早发现不一致) |
node_modules 处理 | 增量更新 | 先整个删除再重装(保证干净) |
| 速度 | 较慢 | 通常更快 |
是否会改 package.json/锁文件 | 会 | 绝不 |
| 适用场景 | 开发时新增/升级依赖 | CI、Docker 构建、生产部署 |
# 典型 CI 流程
npm ci # 严格按锁文件安装
npm test # 跑测试
npm run build # 构建
三、npm 生态
package.json 关键字段逐项解释
| 字段 | 作用 | 注意点 |
|---|---|---|
name | 包名 | 小写、可含 -/_,不能有空格或大写 |
version | 包版本 | 必须符合 SemVer;private: true 时可不发布 |
private | true 表示不发布到 registry | 应用项目务必设为 true,防止误发布 |
description / keywords | 检索用元数据 | 发布到 npm 时有用 |
license | 许可证标识(SPDX) | 如 MIT、Apache-2.0 |
type | "module" 或 "commonjs" | 决定 .js 文件按 ESM 还是 CJS 解析 |
main | CJS 入口 | 老工具链使用 |
module | ESM 入口(非标准,打包器识别) | Vite/Webpack 会优先用 |
exports | 现代入口映射,可限制子路径 | 优先级高于 main/module,可封装内部文件 |
types / typings | TypeScript 类型声明入口 | 与 exports 配合时需在 exports 里也声明 types |
files | 发布时包含哪些文件 | 白名单,能显著减小包体积 |
bin | 安装后可执行的命令名 → 文件映射 | npx/node_modules/.bin 的来源 |
scripts | 可执行脚本别名 | npm run <name> 调用 |
dependencies | 运行时必需依赖 | 会被下游一并安装 |
devDependencies | 仅开发/构建/测试需要 | 下游安装你的包时不会装 |
peerDependencies | 要求宿主环境提供的依赖 | 如插件要求 react: ^18 |
optionalDependencies | 装不上也不报错的依赖 | 如平台相关的原生模块 |
engines | 声明需要的 Node 版本 | 需配合 engine-strict 才强制 |
packageManager | 声明本项目用哪个包管理器及版本(Corepack) | 团队统一工具链的好办法 |
overrides | 强制覆盖传递依赖版本 | 见下文「强制统一版本」 |
dependencies / devDependencies / peerDependencies 的区别
| 类型 | 什么时候需要 | 下游安装你的包时会装吗 | 例子 |
|---|---|---|---|
dependencies | 运行你的代码时必然用到的 | 会 | express、axios、lodash |
devDependencies | 只在开发、构建、测试时用到 | 不会 | typescript、vitest、eslint、@types/* |
peerDependencies | 你不直接依赖它,但要求使用者提供 | 不会自动装(npm 7+ 会尝试装并提示冲突) | 插件的 react、vue |
optionalDependencies | 可有可无,缺了要能降级运行 | 会(失败不中断) | fsevents |
npm install axios # 装进 dependencies
npm install -D vitest # 装进 devDependencies(-D = --save-dev)
npm install --save-exact axios # 精确版本,不加 ^
npm install # 按 package.json 安装全部
npm install -g typescript # 全局安装(慎用,见下文坑)
npm uninstall axios
npm outdated # 列出有新版本的依赖(Current / Wanted / Latest)
npm update # 在 package.json 允许的范围内升级
npm install -g是很多「命令找不到 / 版本不对」问题的根源全局安装的包不属于任何项目,无法随项目锁定版本,多项目共存时会互相覆盖,CI 上也装不到。正确替代方案:
- 项目内的命令行工具 →
devDependencies+npx,或写进scripts;- 真正需要全局的常驻工具(如
pnpm自己、typescript的tsc)→ 用 Corepack(corepack enable)或系统包管理器安装。
scripts 与生命周期钩子
{
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"test": "vitest run",
"lint": "eslint .",
"prepublishOnly": "npm run lint && npm run test && npm run build"
}
}
npm run build # 执行 build 脚本
npm run # 不带参数时列出所有可用脚本
npm test # test / start / stop / restart 可省略 run
npm run build -- --mode production # -- 之后的参数原样传给底层命令
| 生命周期钩子 | 触发时机 |
|---|---|
pre<script> / post<script> | 任何自定义脚本的前后自动执行(如 prebuild、posttest) |
prepare | npm install(本地)与 npm publish(打包)之前;常用来编译 TS |
prepublishOnly | 仅在 npm publish 前执行;适合放校验与测试 |
preinstall / postinstall | 安装本包后执行;恶意包最常用的攻击入口 |
prepack / postpack | 打 tarball 前后 |
postinstall脚本是供应链攻击的头号通道一个包可以在自己的
postinstall里执行任意代码——读取你的~/.ssh、~/.npmrc(含 token)、环境变量里的密钥并上传。防护手段:```bash
# 安装时忽略所有生命周期脚本(最严格的防护,但部分包(如原生模块)需要构建脚本)
npm install --ignore-scripts
# pnpm 的做法:默认就【不】执行依赖的构建脚本,需要显式放行
pnpm approve-builds
```
```ini
# .npmrc 中只允许白名单包运行脚本
ignore-scripts=true
```
除了技术手段,基本纪律是:不装来源不明的包、看下载量与维护活跃度、固定版本、提交锁文件、定期
npm audit。
npx 的用途与安全风险
npx create-vite@latest my-app # 下载并执行一次性命令,不永久安装
npx --no-install tsc --version # 只用本地已安装的版本(不联网)
npx -p typescript tsc --init # 临时提供某个包再执行
npx 的价值在于「跑一次就用完」的工具(脚手架、格式化、一次性脚本),避免污染全局环境。
npx <不认识的包名>等于从互联网直接执行代码
npx在本地找不到该命令时会自动从 registry 下载并执行它。如果你的命令名打错了(比如把eslint打成eslintt),而攻击者恰好注册了这个「拼写错误域名(typosquatting)」包,你就直接执行了它。而且下载下来的包可能带postinstall。安全用法:① 优先
npx --no-install(只用本地已有的);② 明确指定版本npx create-vite@7;③ 只对知名包使用;④ 在生产/CI 环境避免npx拉取未锁定版本的包。
npm / yarn / pnpm 对比
| 维度 | npm | Yarn (Classic 1.x) | Yarn (Berry 2+/4) | pnpm |
|---|---|---|---|---|
| 安装速度 | 中等 | 中等 | 快(配合 PnP 更快) | 最快(内容寻址存储 + 硬链接) |
| 磁盘占用 | 每项目一份完整副本 | 每项目一份 + 全局缓存 | 每项目一份 + 缓存 | 最低(全机同一版本只存一份,硬链接复用) |
node_modules 结构 | 扁平提升(hoisted) | 扁平提升 | 默认不生成(PnP:.pnp.cjs 映射) | 非扁平:根目录只有符号链接,真实包在 .pnpm 里 |
| 幽灵依赖 | 存在 | 存在 | 不存在(PnP 严格) | 不存在(严格模式) |
| 锁文件 | package-lock.json | yarn.lock | yarn.lock | pnpm-lock.yaml |
| workspaces | 支持 | 支持 | 支持 | 支持(pnpm-workspace.yaml) |
| 生态兼容性 | 最好 | 好 | PnP 下部分老工具不兼容 | 好(少数工具不认符号链接,可切 nodeLinker: hoisted) |
| 适合 | 默认选择、新手 | 存量项目 | 追求严格与速度的团队 | 多项目共存、monorepo、在意磁盘 |
幽灵依赖(phantom dependency) 是 npm/yarn 扁平化安装的副作用。因为所有包都被「提升」到 node_modules 顶层,你的代码可以 require('lodash') —— 即使 package.json 里根本没声明 lodash,只是某个依赖碰巧装了它。
// 你的 package.json 里只有 "express",没写 lodash
const _ = require('lodash'); // npm/yarn 下可能"碰巧"能跑
危险之处:某天那个间接依赖升级了、不再依赖 lodash,或者换成 pnpm 安装,你的代码就突然报 Cannot find module 'lodash' —— 而 package.json 从没变过。
pnpm 的解法:它把真实包放在 node_modules/.pnpm/<pkg>@<version>/node_modules/<pkg>,在 node_modules/ 顶层只放符号链接指向你的直接依赖。
node_modules/
├── express -> .pnpm/express@4.19.2/node_modules/express ← 你的直接依赖
└── .pnpm/
├── express@4.19.2/node_modules/
│ ├── express/ ← 真实文件
│ └── lodash/ -> ../../lodash@4.17.21/node_modules/lodash ← 提升到 express 作用域内
└── lodash@4.17.21/node_modules/lodash/ ← 真实文件
结果是:你只能 import 你声明过的包。未声明的 lodash 在顶层不可见,幽灵依赖无法成立。同时所有文件都是硬链接指向全局 store,同一版本的包在整台机器上只存一份。
# pnpm 常用命令(与 npm 基本一一对应)
pnpm install # 等同 npm install(pnpm i)
pnpm add axios # 加入 dependencies
pnpm add -D vitest # 加入 devDependencies
pnpm remove axios
pnpm run build
pnpm dlx create-vite my-app # 等同 npx
pnpm list --depth 0 # 只列直接依赖
pnpm why lodash # 追踪某个包是从哪条依赖链引入的
pnpm store path # 查看全局内容寻址存储位置
# pnpm-workspace.yaml —— monorepo 的包划分
packages:
- 'packages/*'
- 'apps/*'
# 在 monorepo 中只装某个子包的依赖,或给所有子包统一加依赖
pnpm --filter web add axios
pnpm --filter "./packages/**" add -D typescript
pnpm -r run build # 递归在所有子包里执行 build
pnpm -r exec tsc --noEmit
强制统一版本:overrides / resolutions
当传递依赖里出现「同一个包的两个不兼容版本」或「某个间接依赖有已知漏洞但上游没修」时,需要强制指定版本。
{
"overrides": {
"lodash": "4.17.21",
"minimist": "^1.2.8",
"package-a": {
"package-c": "2.0.0"
}
}
}
| 包管理器 | 字段 |
|---|---|
| npm(8.3+) | "overrides" |
| pnpm | "pnpm": { "overrides": {...} } |
| Yarn | "resolutions" |
| pip | 直接在 requirements 里写 pkg==x.y.z,或用 constraints 文件 pip install -r req.txt -c constraints.txt |
| NuGet | 中央包管理 Directory.Packages.props 中的 PackageVersion + 可传递固定 |
overrides是「手术刀」不是「锤子」强制覆盖绕过了上游的兼容性声明,可能让某个库在运行时行为异常,且问题会在很远的地方才暴露。使用原则:① 只针对有明确 CVE 或已确认不兼容的包;② 覆盖的版本尽量贴近原范围(如把
1.2.3提到1.2.9,不要跨大版本);③ 写完必须完整跑一遍测试;④ 在注释或 README 里记录「为什么加这条覆盖、什么时候可以删」。
四、Python 生态
pip 基本用法
# 永远用 python -m pip 而不是裸 pip,确保用的是当前解释器的 pip
python -m pip --version
python -m pip install requests
python -m pip install "requests==2.32.3"
python -m pip install "requests>=2.31,<3"
python -m pip install -r requirements.txt
python -m pip install --upgrade pip
python -m pip uninstall requests
python -m pip list # 已安装包
python -m pip list --outdated # 有新版本的包
python -m pip show requests # 某包详情(版本、依赖、位置)
python -m pip freeze > requirements.txt # 导出当前环境全部包及确切版本
python -m pip check # 检查已安装包之间是否存在依赖冲突
python -m pip check
预期输出:一切正常时打印 No broken requirements found.;有冲突时逐行列出,例如:
urllib3 2.0.0 has requirement charset-normalizer<4,>=2, but you have charset-normalizer 2.0.0.
requirements.txt 与「锁定全部依赖」
# requirements.in —— 只写直接依赖与宽松约束(人写的)
requests>=2.31
flask~=3.0
pytest
# requirements.txt —— 由工具生成,包含【全部】传递依赖并精确固定(机器写的)
certifi==2024.8.30
charset-normalizer==3.3.2
click==8.1.7
flask==3.0.3
idna==3.8
itsdangerous==2.2.0
jinja2==3.1.4
markupsafe==2.1.5
pytest==8.3.2
requests==2.32.3
urllib3==2.2.2
# 生成锁定文件(推荐用 pip-tools 的 pip-compile)
python -m pip install pip-tools
pip-compile requirements.in -o requirements.txt
pip-sync requirements.txt # 让环境与锁定文件完全一致(会卸载多余的包)
为什么必须锁定传递依赖****
只固定直接依赖是不够的:你写
requests>=2.31,它依赖urllib3;某天urllib3发了个破坏性更新的小版本,你的环境就变了。锁定全部依赖(pin all)才能让「今天能跑」= 「半年后新机器上也能跑」。官方的可复现安装指南同时给出了三层强度:固定版本 → 加哈希校验 → 使用 wheelhouse 离线包,详见 pip 官方文档「Repeatable Installs」。```text
# 带哈希校验的锁定写法(防 registry 被替换内容)
requests==2.32.3 --hash=sha256:70761cfe03c773ceb22aa2f67ba0957bd0f75b0c1c...
```
虚拟环境为什么必需
因为一个 Python 解释器只有一份 site-packages。 项目 A 需要 django==3.2,项目 B 需要 django==5.0,装在同一环境里必然有一个跑不起来。
# 创建与激活(Python 3 内置 venv)
python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# Windows (Git Bash / cmd)
source .venv/Scripts/activate
# Linux / macOS
source .venv/bin/activate
python -m pip install -r requirements.txt
deactivate # 退出虚拟环境
预期输出:激活后命令行提示符前出现 (.venv) 前缀,python -c "import sys; print(sys.prefix)" 打印的是项目下的 .venv 目录而不是系统 Python 目录。
虚拟环境的更多细节(包括 venv 与 virtualenv、conda 的区别,以及 PYTHONPATH 的坑)见 Python-08-虚拟环境与包管理。
pyproject.toml 与 PEP 621
pyproject.toml 是现代 Python 项目的统一配置文件:PEP 518 定义了 [build-system],PEP 621 定义了 [project] 表,所有工具配置放在 [tool.*] 下。
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-app"
version = "0.1.0"
description = "一个示例项目"
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
authors = [{ name = "张三", email = "zhangsan@example.com" }]
dependencies = [
"requests>=2.31,<3",
"flask~=3.0",
]
[project.optional-dependencies]
dev = ["pytest>=8", "ruff", "mypy"]
docs = ["sphinx"]
[project.scripts]
my-app = "my_app.cli:main"
[tool.ruff]
line-length = 100
python -m pip install -e ".[dev]" # 以可编辑模式安装,并带上 dev 可选依赖
| 字段 | 作用 |
|---|---|
[build-system].requires | 构建这个包需要哪些工具(如 hatchling、setuptools) |
[build-system].build-backend | 用哪个后端执行构建 |
[project].name / version | name 必须静态声明;version 可静态写或列入 dynamic |
[project].dependencies | 运行时依赖,写法是 PEP 508 依赖说明符 |
[project.optional-dependencies] | 可选依赖组(extras),pip install ".[dev]" 安装 |
[project.scripts] | 生成命令行入口 |
[tool.*] | 任意工具的配置,如 [tool.ruff]、[tool.pytest.ini_options] |
uv / poetry / pdm 的定位对比
| 工具 | 定位 | 依赖声明 | 锁文件 | 特点 |
|---|---|---|---|---|
| pip | 官方基础安装器 | requirements.txt | 无(需 pip-tools 补) | 最通用、最保守;只负责装,不负责环境与项目 |
| pip-tools | 给 pip 加锁定能力 | requirements.in | requirements.txt | 轻量、贴近原生;无虚拟环境管理与发布流程 |
| Poetry | 完整的项目管理工具 | pyproject.toml([tool.poetry],新版支持 PEP 621) | poetry.lock | 依赖解析强、可构建发布;历史上与 PEP 621 有分歧 |
| PDM | 现代 PEP 标准派 | pyproject.toml(标准 PEP 621) | pdm.lock | 严格遵循 PEP 标准,支持 PEP 582 思路 |
| uv | Rust 实现的高速一体化工具 | pyproject.toml | uv.lock | 同时替代 pip/venv/pip-tools/virtualenv,速度极快;生态较新 |
# uv 示例
uv venv # 创建虚拟环境
uv pip install -r requirements.txt # 兼容 pip 的安装接口
uv add requests # 加入 pyproject 依赖并更新 uv.lock
uv sync # 严格按 uv.lock 同步环境
uv run pytest # 在项目环境里执行命令
# Poetry 示例
poetry init
poetry add requests
poetry add --group dev pytest
poetry install --no-root
poetry lock --no-update
怎么选
学习与脚本:
venv+pip+requirements.txt,最不容易出错,也最通用。要和别人协作的库:
pyproject.toml(PEP 621)+ 你选的工具,锁文件一并提交。想快:
uv。它向下兼容 pip 的接口,可以渐进迁移。无论用哪个,锁文件必须提交,这是唯一的硬要求。
国内镜像源配置
PyPI 官方源在国内访问不稳定,换成国内镜像能显著提速。
# 临时使用(单条命令)
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 永久配置(写入用户级配置文件)
python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
python -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
# 查看当前配置来源
python -m pip config list -v
python -m pip config debug
也可以直接手写配置文件:
# Windows: %APPDATA%\pip\pip.ini
# Linux/macOS: ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
extra-index-url = https://mirrors.aliyun.com/pypi/simple/
timeout = 60
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
mirrors.aliyun.com
| 镜像 | 地址 |
|---|---|
| 清华大学 TUNA | https://pypi.tuna.tsinghua.edu.cn/simple |
| 阿里云 | https://mirrors.aliyun.com/pypi/simple/ |
| 腾讯云 | https://mirrors.cloud.tencent.com/pypi/simple/ |
| 华为云 | https://mirrors.huaweicloud.com/repository/pypi/simple/ |
| 中科大 USTC | https://pypi.mirrors.ustc.edu.cn/simple/ |
npm 同理,可换用 npmmirror:
npm config set registry https://registry.npmmirror.com
npm config get registry
# 或用项目级 .npmrc 而非全局,避免影响其他项目
镜像源的取舍
镜像同步有延迟(通常几分钟到几小时),刚发布的新版本可能还没有。另外镜像属于第三方信任链:企业内网应使用自建私有源(Nexus、Artifactory、devpi)而不是公共镜像。切换镜像后如果出现「包不存在」,先换回官方源确认是不是同步延迟。
五、.NET 生态(NuGet)
基本概念
| 概念 | 说明 |
|---|---|
| 包(package) | .nupkg 文件,本质是一个 zip,含程序集、.nuspec 元数据、依赖声明 |
| 源(source) | 包的来源,默认是 https://api.nuget.org/v3/index.json,也可配置私有源 |
| 全局包缓存 | ~/.nuget/packages(Windows 为 %USERPROFILE%\.nuget\packages),同一版本全局只存一份 |
<PackageReference> | 现代 SDK 风格项目的依赖声明方式(替代老的 packages.config) |
obj/project.assets.json | 还原(restore)后生成的依赖图快照,类似锁文件但默认不提交 |
packages.lock.json | 可选的真正锁文件,需设置 RestorePackagesWithLockFile 启用 |
dotnet add package Newtonsoft.Json # 安装最新稳定版
dotnet add package Newtonsoft.Json --version 13.0.3 # 指定版本
dotnet add package Newtonsoft.Json --version 13.0.* # 浮动版本
dotnet remove package Newtonsoft.Json
dotnet list package # 列出顶层依赖
dotnet list package --include-transitive # 含传递依赖
dotnet list package --outdated # 有可用更新的包
dotnet list package --vulnerable --include-transitive # 有已知漏洞的包
dotnet restore # 只还原,不构建
预期输出:dotnet list package --outdated 打印一张表,列为 Project / Top-level Package / Requested / Resolved / Latest。
<!-- 现代 .csproj 中的依赖声明 -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Serilog" Version="4.0.2" />
<PackageReference Include="xunit" Version="2.9.0" PrivateAssets="all" />
</ItemGroup>
</Project>
| 元数据 | 作用 |
|---|---|
Version | 版本或版本范围 |
PrivateAssets="all" | 不把该依赖传递给下游(常用于分析器、测试框架) |
IncludeAssets / ExcludeAssets | 精细控制使用包的哪些部分(compile/runtime/build/analyzers) |
VersionOverride | 在中央包管理下对单个项目破例指定版本 |
NuGet 版本范围语法
| 写法 | 含义(区间) |
|---|---|
1.0.0 | 最低版本 (NuGet 的裸版本号是下界,不是精确匹配!) |
[1.0.0] | 精确版本 |
(1.0.0,) | 大于 |
[1.0.0,2.0.0) | |
[1.0.0,2.0.0] | |
(,2.0.0] | 小于等于 |
[1.0.0,2.0.0) 中的 ( | 开区间(不含),[ 闭区间(含) |
1.0.* | 浮动: |
* | 浮动:最新版 |
NuGet 的裸版本号与 npm 语义不同
在 npm 里
"lodash": "4.17.21"表示精确 4.17.21;在 NuGet 里Version="4.17.21"表示最低要求 4.17.21,还原时可能被提升到更高版本(由依赖图决定)。要精确锁定必须写成[4.17.21]。这是从 npm 转过来的人最常踩的坑。
中央包管理(Central Package Management, CPM)
多项目解决方案里,同一个包在不同项目写不同版本会导致「版本漂移」甚至运行时加载错误。CPM 把版本集中到根目录的 Directory.Packages.props:
<!-- Directory.Packages.props(放在解决方案根目录) -->
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Serilog" Version="4.0.2" />
<PackageVersion Include="xunit" Version="2.9.0" />
</ItemGroup>
</Project>
<!-- 各项目文件里不再写 Version -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Serilog" />
</ItemGroup>
</Project>
dotnet new packagesprops # 用模板生成 Directory.Packages.props
| 相关属性 | 作用 |
|---|---|
ManagePackageVersionsCentrally | 开启/关闭 CPM |
CentralPackageTransitivePinningEnabled | 允许直接把传递依赖提升为顶层并固定版本(不允许降级,否则报 NU1109) |
CentralPackageVersionOverrideEnabled | 是否允许单个项目用 VersionOverride 破例 |
GlobalPackageReference | 让解决方案中每个项目都引用的包(如版本管理、分析器) |
使用 CPM 时的
NU1507警告如果
nuget.config里配置了多个包源,CPM 会记录警告NU1507,提示你需要用包源映射(package source mapping)明确「哪个包从哪个源下载」。这不是错误,但在企业环境中应认真配置,否则可能出现「同名包从错误的私有源下载」这类供应链风险。
私有源与 nuget.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear /> <!-- 清空继承来的源,保证构建可复现 -->
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="company" value="https://nuget.internal.example.com/v3/index.json" />
</packageSources>
<packageSourceCredentials>
<company>
<add key="Username" value="%NUGET_USER%" />
<add key="ClearTextPassword" value="%NUGET_TOKEN%" />
</company>
</packageSourceCredentials>
<config>
<add key="globalPackagesFolder" value="D:\nuget-packages" />
</config>
</configuration>
dotnet nuget list source # 查看当前生效的源
dotnet nuget add source https://nuget.internal.example.com/v3/index.json -n company
dotnet nuget disable source company
dotnet nuget locals all --list # 查看各类缓存目录
dotnet nuget locals all --clear # 清理本地缓存(解决"缓存了错误包"的问题)
千万不要把私有源的密码明文提交到仓库
nuget.config里使用%NUGET_TOKEN%这类环境变量占位符(NuGet 会自动展开),或改用dotnet nuget add source --store-password-in-clear-text false配合凭据管理器。一旦含明文密码的文件被提交,必须立刻视为泄露并轮换凭据,然后用git filter-repo清理历史(见 工具-01-Git版本控制)。
更多 .NET 项目结构与工具链内容见 CSharp-07-dotnet项目与工具链。
六、依赖管理通用原则
| 原则 | 说明 | 具体做法 |
|---|---|---|
| 最小依赖 | 每一个依赖都是长期维护成本与攻击面 | 能自己写 30 行解决的小工具就不要引入;引入前评估维护活跃度、体积、许可证 |
| 区分直接与传递依赖 | 你只对直接依赖负责,但传递依赖同样会在你的进程里运行 | 定期 npm ls --all / pipdeptree 看全貌;用锁文件固化 |
| 锁定并提交锁文件 | 可复现构建的前提 | package-lock.json、pnpm-lock.yaml、poetry.lock、packages.lock.json |
| 定期审计漏洞 | 新 CVE 随时公布 | npm audit、pip-audit、dotnet list package --vulnerable |
| 小步升级 | 一次升一个 MAJOR,出问题容易定位 | 不要攒半年一次升 20 个包 |
| 升级后必须回归测试 | SemVer 是承诺不是保证,0.x 更是完全没有保证 | 升级独立成一个提交/PR,跑全量测试 |
| 区分运行时与开发依赖 | 生产镜像不该带上测试框架 | devDependencies、[project.optional-dependencies]、PrivateAssets |
| 依赖要有退出计划 | 关键依赖停止维护时要能替换 | 隔离在薄封装层后面,避免全项目直接调用其 API |
漏洞审计命令
npm audit # 报告漏洞及依赖路径
npm audit --json # 机器可读
npm audit --omit=dev # 只审计生产依赖
npm audit fix # 在 SemVer 范围内自动修复(安全)
python -m pip install pip-audit
pip-audit # 审计当前环境
pip-audit -r requirements.txt # 审计需求文件而不安装
pip-audit --fix # 尝试自动修复
dotnet list package --vulnerable --include-transitive
dotnet list package --deprecated # 已被弃用的包
npm audit fix --force会跨大版本强制升级,可能直接改坏项目```bash
npm audit fix --force # 危险:允许安装 SemVer 之外(含 MAJOR)的版本
```
它的做法是忽视
^约束,把包升到「修复了漏洞的任意版本」。结果可能是某个依赖从 2.x 跳到 4.x、API 全部改变、构建直接失败,而你还不知道是哪一步弄坏的。稳妥流程:① 先
npm audit看清漏洞在哪条依赖链;② 优先升级直接依赖到已修复版本(npm install pkg@latest);③ 只有间接依赖时,用overrides定点覆盖到最小可用版本;④ 每次只改一处并提交,跑测试;⑤ 无法修复且影响运行时,评估风险后记录在案。
单体仓库(monorepo)中的依赖共享
monorepo 是把多个包/应用放在同一个仓库里。好处是跨包改动可以原子提交、共享工具链与依赖版本;代价是依赖必须显式划分作用域。
| 生态 | workspace 机制 | 声明位置 |
|---|---|---|
| npm | workspaces 字段 | 根 package.json 的 "workspaces": ["packages/*"] |
| pnpm | pnpm-workspace.yaml | 单独的 YAML 文件 |
| Yarn | workspaces 字段 | 根 package.json |
| Python | uv / PDM / Poetry 的 workspace 支持 | [tool.uv.workspace]、[tool.pdm]、Poetry 的 path 依赖 |
| .NET | 解决方案(.sln)+ CPM | Directory.Packages.props 统一版本 |
// npm workspaces
{
"name": "my-monorepo",
"private": true,
"workspaces": ["packages/*", "apps/*"]
}
npm install -w packages/ui lodash # 只给 ui 子包装依赖
npm run build -w apps/web # 只在 web 子包执行脚本
npm install # 根目录一次安装所有子包依赖
monorepo 的关键收益之一是依赖版本统一:所有子包共用根 node_modules(或 pnpm 的 store 硬链接),同一个包在整仓库只有一个版本,从根本上减少「两个子包用了不兼容版本」的问题。但要注意:根 package.json 不应放业务依赖,只放工具链(lint、测试、构建)依赖。
七、依赖冲突的排查方法论
第一步:读懂依赖树
# npm:查看某包为什么被安装、装了哪些版本
npm ls lodash
npm ls --all # 完整依赖树(输出很长,建议配合 --depth 限制)
npm ls --depth=1
npm explain lodash # 说明为什么这个包在依赖树里
npm why lodash # explain 的别名
# pnpm
pnpm why lodash
pnpm list --depth 2
预期输出(npm ls lodash):
my-app@1.0.0 D:\code\my-app
├─┬ express@4.19.2
│ └── lodash@4.17.21
└─┬ some-lib@2.3.0
└── lodash@3.10.1 ← 冲突:同一棵树里有两个大版本
python -m pip install pipdeptree
pipdeptree # 以树形显示谁依赖谁
pipdeptree --reverse --packages urllib3 # 反向:谁依赖了 urllib3
pipdeptree --warn silence # 只看冲突
pipdeptree --json-tree # 机器可读
dotnet list package --include-transitive
dotnet nuget why <项目> <包名> # .NET 9+ 提供,追踪传递依赖来源
第二步:判断冲突类型
| 现象 | 含义 | 性质 |
|---|---|---|
| 同一包出现两个大版本且都被加载 | 真正的冲突,可能运行时行为不一致 | 严重 |
| 同一包出现两个小版本 | 通常无害(重复安装,体积略大) | 轻微 |
peer dependencies 警告 | 你的依赖要求某个版本的 React,但项目装的是另一个 | 需要处理 |
Cannot find module 'x' | 幽灵依赖在严格模式下暴露,或依赖未声明 | 补声明 |
ERESOLVE unable to resolve dependency tree | npm 无法找到同时满足所有约束的版本组合 | 需要决策 |
pip check 报 broken requirements | 已安装包之间的约束被破坏 | 需要决策 |
第三步:三种解决路径
| 路径 | 做法 | 适用 | 风险 |
|---|---|---|---|
| 升级(首选) | 把上层依赖升到同时兼容两个下界的版本 | 上层有新版本可用 | 需要回归测试 |
| 降级 | 把某个包降到与另一方兼容的版本 | 升级不可行(如上层已停止维护) | 可能失去安全修复 |
| 强制覆盖 | overrides / resolutions / constraints 指定唯一版本 | 前两条都走不通,或有 CVE 必须修 | 绕过兼容性声明,行为可能异常 |
# npm 的 ERESOLVE 报错时的处理顺序
# ① 先读完整报错,它会打印冲突的两个约束,例如:
# Could not resolve dependency: peer react@"^17.0.0" from some-lib@1.0.0
npm install --legacy-peer-deps # ② 退回到 npm 6 的宽松 peer 处理(临时手段)
npm install --force # ③ 更强硬,绕过冲突检查(危险,最后手段)
--legacy-peer-deps和--force是止痛药不是解药它们让安装「成功」了,但冲突依然存在,问题会推迟到运行时以
undefined is not a function的形式爆发。正确做法是:查清some-lib是否有支持 React 18 的新版本(升级路径),或用overrides显式钉住react的版本并接受后果。请把这类临时开关限制在本机,不要写进 CI 配置或.npmrc提交到仓库。
为什么必须区分直接依赖与传递依赖
- 你可以直接控制的只有直接依赖的版本范围;
- 传递依赖的版本由解析器决定,你只能通过「升级直接依赖」或「强制覆盖」来间接影响;
- 因此当出现漏洞时,正确的问题是:「哪个直接依赖引入了这个有漏洞的传递依赖?」 —— 这就是
npm why/pipdeptree --reverse要回答的问题; - 只知道「
lodash有漏洞」而没有定位到引入路径,就会陷入「删了又回来」的循环。
八、新项目依赖清单该怎么定(实践建议表)
| 类别 | 建议做法 | 具体示例 |
|---|---|---|
| 核心运行时 | 只放真正必需的,逐个问「没有它行不行」 | Web 框架、HTTP 客户端、数据库驱动 |
| 工具链 | 全部放 devDependencies / optional-dependencies | 编译、打包、Lint、格式化、类型检查 |
| 测试 | 测试框架 + 断言库 + 覆盖率,都放 dev | vitest/pytest/xunit |
| 类型声明 | @types/* 一律 dev;运行时库自带类型则不需要 | @types/node |
| 原生/平台相关 | 用 optionalDependencies,提供降级路径 | fsevents、sharp |
| 版本范围 | 应用用 ^;库对依赖用 ^,对自己 API 严守 SemVer | "axios": "^1.7.0" |
| 锁定 | 立刻提交锁文件,CI 用 npm ci / uv sync --frozen | 见前文 |
| 工具链统一 | 在 package.json 声明 packageManager,用 Corepack 固定版本 | "packageManager": "pnpm@9.12.0" |
| 运行时版本 | 声明 engines + .nvmrc / requires-python / TargetFramework | ">=20.11"、">=3.11" |
| 安全基线 | 提交前跑一次审计,CI 里加审计步骤 | npm audit --omit=dev --audit-level=high |
| 许可合规 | 检查依赖许可证是否与项目兼容 | 用 license-checker、pip-licenses |
| 数量控制 | 直接依赖超过 ~30 个时重新审视每一行 | 定期清理不再使用的包 |
| 文档化 | 记录「为什么选它」与「备选方案」 | 在 README 或 ADR 里写明 |
怎么用:一个完整的新项目依赖落地流程
# ---------- Node.js 项目 ----------
mkdir my-app && cd my-app
npm init -y
# 编辑 package.json:设置 private: true、license、engines、packageManager
npm pkg set private=true
npm pkg set engines.node=">=20.11"
npm pkg set packageManager="pnpm@9.12.0"
npm install express # 运行时依赖
npm install -D typescript vitest @types/node # 开发依赖
npm ls --depth=0 # 确认直接依赖清单
npm audit --omit=dev # 审计生产依赖
git add package.json package-lock.json
git commit -m "chore: 初始化项目依赖"
预期输出:npm ls --depth=0 打印两段,dependencies: 下列出 express@4.19.2,devDependencies: 下列出 typescript/vitest/@types/node 及版本号。
# ---------- Python 项目 ----------
mkdir my-app && cd my-app
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
# 编写 pyproject.toml 后以可编辑模式安装
python -m pip install -e ".[dev]"
python -m pip freeze > requirements.lock.txt # 生成锁定的全量清单
python -m pip check # 确认没有冲突
pip-audit # 审计漏洞
# ---------- .NET 项目 ----------
dotnet new webapi -n MyApp
cd MyApp
dotnet new packagesprops # 生成 Directory.Packages.props(解决方案根目录)
dotnet add package Serilog
dotnet list package --include-transitive
dotnet list package --vulnerable
dotnet restore --use-lock-file # 生成 packages.lock.json 并后续使用
CI 中的依赖步骤模板
```bash
# Node
npm ci && npm audit --omit=dev --audit-level=high && npm run build && npm test
# Python
python -m pip install -r requirements.lock.txt && pip-audit && pytest
# .NET
dotnet restore --locked-mode && dotnet list package --vulnerable && dotnet test
```
三个生态的共同点:先用锁文件(
ci/--locked-mode/--frozen)安装,再审计,再测试。顺序反了(先测后审计)就等于漏掉了最该拦住的环节。
常见坑
坑 1:
.gitignore里把锁文件忽略了有些人觉得锁文件「是自动生成的、提交它会天天冲突」,于是忽略掉。这会让构建完全不可复现,而且不同人装出不同的传递依赖版本。「天天冲突」的正确解法是:冲突时重新生成锁文件(删掉后按声明文件重装),而不是不提交它。
坑 2:用
npm install <pkg>在 CI 里安装依赖
npm install会重新解析依赖树并就地改写锁文件,等于每次都可能是新环境。CI 里永远用npm ci(pnpm 用pnpm install --frozen-lockfile,uv 用uv sync --frozen),它会在锁文件与声明文件不一致时直接失败——这正是你想要的行为。
坑 3:裸
pip install装到系统 Python 里在没激活虚拟环境的情况下
pip install,会把包装到系统site-packages。几年下来系统 Python 环境会被几十个互不兼容的包污染,甚至影响操作系统自带的工具。防护:每次开新终端先确认提示符有没有(.venv);用python -m pip而不是pip;现代发行版(Debian 12+、Ubuntu 23.04+)默认启用 PEP 668「外部管理环境」保护,会直接拒绝安装——这时应该创建虚拟环境,而不是加--break-system-packages绕过。
坑 4:把
0.x版本的依赖当稳定依赖用
0.x的 MINOR 升级允许破坏性变更。^0.5.0允许升到0.6.0,如果该库在 0.6 里删了某个 API,你的代码会在下次npm install后突然崩掉。对策:对0.x依赖使用精确版本("lib": "0.5.3")或~0.5.3,并且升级时当成 MAJOR 升级来对待。
坑 5:跨生态混用包管理器
同一个 Node 项目里出现
package-lock.json和pnpm-lock.yaml两个锁文件,说明有人用不同工具装过。这两份锁文件描述的是不同的node_modules结构,谁最后跑谁生效,结果是团队里每个人的依赖树都不一样。解决:删掉多余的锁文件与node_modules,在package.json的packageManager字段与 README 里明确指定唯一工具,然后用 Corepack 强制。
坑 6:删掉
node_modules就以为「重装能好」有时确实有效(尤其是缓存损坏、原生模块编译平台不对时),但要按顺序做:
```bash
rm -rf node_modules
npm cache verify # 校验缓存(不要动辄 npm cache clean --force)
npm ci # 按锁文件干净重装
```
如果
npm ci后仍然报错,就该去看具体报错,而不是继续「删了重装」——重复无效操作不会带来新信息。
坑 7:把
pip/npm的凭据写进仓库
.npmrc里的//registry.example.com/:_authToken=xxx、pip.ini里的密码、nuget.config里的ClearTextPassword,一旦提交就是泄露。统一改用环境变量占位符(${NPM_TOKEN}、%NUGET_TOKEN%)并在 CI 的 secret 里配置。
练习题
练习 1:版本区间计算
项目里写着
"foo": "^1.4.2"、"bar": "~2.1.0"、"baz": "0.5.1"。请分别写出它们允许的版本区间(用 LaTeX 区间表示);再回答:如果foo发布了1.9.9和2.0.0,npm update会升级到哪个?baz发布了0.5.2和0.6.0,会升级到哪个?
练习 2:识别幽灵依赖
某个
package.json里只声明了express,但代码里require('lodash')能跑通。请解释原因,写出两种验证这是幽灵依赖的方法,并说明该代码迁移到 pnpm 后会发生什么、怎么修。
练习 3:依赖冲突排查
npm install报ERESOLVE unable to resolve dependency tree,提示某个插件要求react@^17但项目装的是react@18。请写出你的排查步骤(含具体命令),并给出三种可能的解决方案及其取舍。
练习 4:Python 环境可复现
你的团队里有人说「我本地跑得好好的,服务器上
ImportError」。请设计一套能避免这类问题的依赖管理方案:说明用什么文件、装什么内容、CI 里执行什么命令、为什么这样能避免问题。
练习 5:审计与升级
npm audit报告某个传递依赖有高危漏洞,但你的直接依赖都已经是最新版了。请写出三种处理路径,说明各自的命令与风险,并给出你的推荐顺序。
FAQ
Q1:
package-lock.json和yarn.lock能共存吗?可以只提交一个吗?技术上可以共存,但不应该。锁文件是包管理器私有的格式,npm 读不懂
pnpm-lock.yaml的语义,两者同时存在会导致「谁最后安装谁生效」。正确做法是在仓库里只保留与团队约定工具对应的那一个锁文件,在package.json的packageManager字段中声明工具与版本,在 README 中写明「本项目使用 pnpm,请勿使用 npm install」。如果要迁移工具,应一次性删除旧锁文件与node_modules,用新工具重新生成并提交一个独立的重构提交。
Q2:
devDependencies里的包会在生产环境运行吗?正常情况下不会:当你的包被别人安装时,npm/pnpm 只装
dependencies,跳过devDependencies。但要注意三点:① 如果你的构建产物依赖某个包在运行时存在(比如把typescript当成运行时编译 TS 的库),那它必须在dependencies里;② 直接部署源码(而不是构建产物)到生产、并用npm install --production之外的方式安装,就可能把 dev 依赖一并装进去;③ 容器镜像里应使用多阶段构建,只在最终阶段安装生产依赖,见 后端-07-Docker与容器化。
Q3:为什么
npm install有时会改动package-lock.json里我没碰过的包?因为
npm install会重新解析整棵依赖树:新增一个包可能改变了解析器对其他包的版本选择(例如去重、提升策略变化),于是锁文件里其他条目也被更新。这就是为什么在 CI 里必须用npm ci——它只读锁文件,绝不改写。开发时如果只想加一个包而不想扰动其他包,可以用npm install pkg --save-exact并仔细 review 锁文件的 diff。
Q4:语义化版本能完全避免破坏性升级吗?
不能。SemVer 是社会契约,不是技术保证:① 有些库在 MINOR 版本里偷偷做了破坏性变更(违反约定);② 「破坏性」的定义有主观性——一个 bug 修复可能让依赖该 bug 行为的代码失效;③
0.x版本完全没有保证;④ 传递依赖的升级可能让你的直接依赖出现未测试过的组合。所以真正的保护是三重:锁文件(不被动升级)+ 测试(升级后能发现问题)+ 小步升级(出问题能快速定位到是哪一步)。
相关笔记
- Python-08-虚拟环境与包管理 —— Python 侧虚拟环境、pip 与依赖管理的完整展开
- CSharp-07-dotnet项目与工具链 —— .NET 解决方案、NuGet 还原与发布流程
- JavaScript-06-模块化与工程化 —— CommonJS / ES Module 与 npm 包解析规则的关系
- 工具-01-Git版本控制 —— 锁文件的提交、冲突处理与
.gitignore的边界 - 工具-02-命令行与Shell —— 所有包管理操作都在命令行完成
- 工具-08-CICD入门 ——
npm ci、pip-audit等命令如何嵌入持续集成流水线 - 后端-07-Docker与容器化 —— 多阶段构建中如何只安装生产依赖
参考来源
- npm Docs · package.json 字段说明 —— 各字段的官方定义
- npm Docs · About semantic versioning ——
^、~、x范围的确切语义 - npm Docs · package spec(版本范围语法) —— 依赖说明符的完整语法参考
- npm Docs · npm ci ——
ci与install的官方差异说明 - npm Docs · npm ls —— 依赖树查看
- npm Docs · npm audit —— 漏洞审计
- npm Docs · npm scripts —— 生命周期钩子与
pre/post规则 - pnpm 中文文档 · 项目初衷 —— 内容寻址存储、非扁平
node_modules与幽灵依赖问题 - pnpm 中文文档 · 工作空间 —— monorepo 的
pnpm-workspace.yaml用法 - pip 官方文档 · Repeatable Installs —— 固定版本、哈希校验、wheelhouse 三层可复现方案
- pip 官方文档 · pip check —— 依赖一致性检查
- Python Packaging User Guide · pyproject.toml 规范 —— PEP 518 / PEP 621 定义的
[build-system]与[project]表 - Python Packaging User Guide · Version specifiers ——
==、~=、>=等说明符的语义 - Python 官方教程 · 虚拟环境和包 ——
venv与 pip 的中文入门 - Microsoft Learn · NuGet 中央包管理 ——
Directory.Packages.props、可传递固定与VersionOverride - Microsoft Learn · NuGet 包版本控制 —— 版本范围语法与浮动版本
- Microsoft Learn · dotnet add package —— 添加包的 CLI 用法
- Microsoft Learn · dotnet list package ——
--outdated、--vulnerable、--include-transitive - Microsoft Learn · nuget.config 参考 —— 私有源与凭据配置