项目跑不起来？先看依赖有没有对上
你是不是也遇到过这种情况：刚从仓库拉下代码，兴冲冲地执行 npm install 或 pip install -r requirements.txt，结果一运行就报错，提示某个模块找不到，或者版本不兼容。这时候别急着重装环境，大概率是源码依赖管理出了问题。
尤其在团队协作中，不同人本地环境略有差异，加上依赖版本频繁更新，很容易出现“我这边好好的，到你就挂了”的尴尬局面。
依赖版本锁定不到位
最常见的问题是没把依赖版本锁死。比如 package.json 里写的是 "lodash": "^4.17.0"，这个 ^ 符号意味着安装 4.17.0 及其后续的补丁或小版本更新。听起来方便，但万一 4.18.0 引入了破坏性变更，你的构建就可能突然失败。
解决办法很简单：用 lock 文件。npm 有 package-lock.json，yarn 有 yarn.lock，Python 的 pipenv 生成 Pipfile.lock，这些文件记录了实际安装的精确版本。记得把它提交到 Git，别加进 .gitignore 里。
多个依赖来源冲突
有些项目混用了多种依赖管理方式。比如前端用 Webpack 打包，同时又通过 script 标签引入 CDN 上的库，两者版本不一致，运行时就会出问题。更隐蔽的是，A 依赖引入了 jQuery 3.5，B 依赖偷偷加载了 1.11，低版本覆盖高版本，功能直接残废。
这时候可以用工具分析依赖树。npm 下执行 npm ls jquery，就能看到谁引入了哪个版本。Webpack 还能配置 externals 避免重复打包。
私有依赖拉不下来
公司内部的 UI 组件库、工具包通常放在私有 npm 仓库或 Git 仓库里。新同事克隆项目后，执行 install 卡住或报 403 错误，基本就是认证没配好。
以 npm 为例，需要在 .npmrc 文件里配置 registry 和 token：
registry=https://registry.npmjs.org/
@mycompany:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=ghp_xxxxxxxxxxxxxxxxxxxxxx没有这个文件，或者 token 过期，都会导致私有包无法下载。别忘了把这个配置文件也纳入版本管理（但别把 token 明文提交！可以用环境变量注入）。
构建产物混入源码目录
有些项目在发布前会把依赖打包进 dist 或 lib 目录，结果有人误把 node_modules 里的内容也提交了。下次别人拉代码，看似依赖齐全，实则版本混乱，甚至包含不兼容的二进制文件。
.gitignore 一定要加上：
/node_modules
/venv
/dist
/build避免把临时文件和依赖塞进仓库。
跨语言项目更易踩坑
现在不少项目是 Python 写后端，Node.js 做构建，再嵌入 C++ 编译的插件。这种多层依赖结构一旦出问题，排查起来像拆炸弹。
比如用 Node-gyp 编译原生模块时，提示 Python 版本不对。明明装了 Python 3，系统却默认指向 Python 2。这时候得显式指定：
npm config set python /usr/bin/python3或者在 .npmrc 里写明 python=/usr/bin/python3。
关键是要理清每一层依赖的上下文环境，别让工具自己猜。
日常建议
定期更新依赖没问题，但别图省事直接 upgrade 到最新版。先在测试分支试跑，用自动化测试兜底。可以借助 Dependabot 或 Renovate 自动提 PR，结合 CI 流水线验证兼容性。
写 README 时别只写一句“运行 npm install”，最好注明推荐的 Node 版本、是否需要额外配置权限、是否有系统级依赖（如 Redis、PostgreSQL）要提前装好。
源码依赖不是越新越好，也不是越多越强。管好了，开发顺滑如德芙；管不好，天天都在救火。