w wyl123ly 的博客
MD

工具-03-包管理器

58 KB 2026.10.11 原文件

工具-03-包管理器

这篇笔记讲什么

包管理器(package manager)负责自动下载、安装、升级、卸载第三方代码,并解决这些代码之间的依赖关系。这篇笔记讲清三件事:语义化版本(SemVer)与锁文件为什么是工程可靠性的基石;npm / pip / NuGet 三大生态的具体用法;依赖冲突的排查与升级策略。

读完你应该能够:看懂 package.json 里每一个字段;解释 npm ci 与 npm install 的区别;在一个报「版本冲突」的项目里定位到具体是哪两个包在打架;给新项目定出一份合理的依赖清单。

是什么

包(package) 是可复用的代码分发单元,通常包含代码、元数据(名字、版本、作者、许可证)和依赖声明。包管理器是安装和管理这些包的工具,它同时提供了四样东西:

  1. 一个仓库(registry):集中存放包的服务器,如 npm registry、PyPI、NuGet.org。
  2. 一份依赖声明格式:package.json、pyproject.toml/requirements.txt、.csproj。
  3. 一个解析器(resolver):读依赖声明,算出一组能同时满足所有约束的版本。
  4. 一份锁文件(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@1B 崩(调用了 2.x 才有的接口)
只装 C@2A 崩(调用了已被删除的接口)
两个都装取决于语言: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.30.x 时只允许 PATCH 升级
^0.0.30.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),以及整棵依赖树的形状。

生态锁文件是否必须提交到版本控制
npmpackage-lock.json必须
pnpmpnpm-lock.yaml必须
Yarnyarn.lock必须
pip(requirements 方式)requirements.txt(全部固定)必须
Poetry / PDM / uvpoetry.lock / pdm.lock / uv.lock必须
NuGetpackages.lock.json(需手动启用)推荐(应用项目)

锁文件保证可复现构建的原理(两个层次):

  1. 版本可复现:安装时优先按锁文件里的确切版本下载,而不是重新按 ^ 求解。所以 CI、同事、生产服务器装出来的是同一组版本。
  2. 内容可复现:锁文件里保存了每个包的 integrity 哈希(如 sha512-...)。下载后校验哈希,不匹配就直接报错。这同时防御了「registry 被入侵替换包内容」这类供应链攻击。

什么情况下锁文件会「失效」

- 有人手动改 package.json 的依赖范围并重新 install,锁文件被就地更新;

- 有人在 .gitignore 里把锁文件忽略了(这是反模式);

- 用了 npm install <pkg> 而不是 npm install(会顺带升级其他包);

- 合并两个分支时锁文件冲突被随手「解决」成某一方的版本。

正确做法:锁文件的冲突不要手工编辑,应删掉锁文件后重新用声明文件安装一次(rm package-lock.json && npm install),并跑测试。

# npm ci:面向 CI 的「严格按锁文件安装」
npm ci
维度npm installnpm 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 时可不发布
privatetrue 表示不发布到 registry应用项目务必设为 true,防止误发布
description / keywords检索用元数据发布到 npm 时有用
license许可证标识(SPDX)如 MIT、Apache-2.0
type"module" 或 "commonjs"决定 .js 文件按 ESM 还是 CJS 解析
mainCJS 入口老工具链使用
moduleESM 入口(非标准,打包器识别)Vite/Webpack 会优先用
exports现代入口映射,可限制子路径优先级高于 main/module,可封装内部文件
types / typingsTypeScript 类型声明入口与 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)
preparenpm 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 对比
维度npmYarn (Classic 1.x)Yarn (Berry 2+/4)pnpm
安装速度中等中等快(配合 PnP 更快)最快(内容寻址存储 + 硬链接)
磁盘占用每项目一份完整副本每项目一份 + 全局缓存每项目一份 + 缓存最低(全机同一版本只存一份,硬链接复用)
node_modules 结构扁平提升(hoisted)扁平提升默认不生成(PnP:.pnp.cjs 映射)非扁平:根目录只有符号链接,真实包在 .pnpm 里
幽灵依赖存在存在不存在(PnP 严格)不存在(严格模式)
锁文件package-lock.jsonyarn.lockyarn.lockpnpm-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 / versionname 必须静态声明;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.inrequirements.txt轻量、贴近原生;无虚拟环境管理与发布流程
Poetry完整的项目管理工具pyproject.toml([tool.poetry],新版支持 PEP 621)poetry.lock依赖解析强、可构建发布;历史上与 PEP 621 有分歧
PDM现代 PEP 标准派pyproject.toml(标准 PEP 621)pdm.lock严格遵循 PEP 标准,支持 PEP 582 思路
uvRust 实现的高速一体化工具pyproject.tomluv.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
镜像地址
清华大学 TUNAhttps://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/
中科大 USTChttps://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 机制声明位置
npmworkspaces 字段根 package.json 的 "workspaces": ["packages/*"]
pnpmpnpm-workspace.yaml单独的 YAML 文件
Yarnworkspaces 字段根 package.json
Pythonuv / PDM / Poetry 的 workspace 支持[tool.uv.workspace]、[tool.pdm]、Poetry 的 path 依赖
.NET解决方案(.sln)+ CPMDirectory.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 treenpm 无法找到同时满足所有约束的版本组合需要决策
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、格式化、类型检查
测试测试框架 + 断言库 + 覆盖率,都放 devvitest/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与容器化 —— 多阶段构建中如何只安装生产依赖

参考来源