本文详解为何在 git 分支切换后 react/vite/webpack 项目频繁报“module not found”（如 react-redux、@reduxjs/toolkit 等模块缺失），并提供根治方案：禁止提交 `node_modules`、规范依赖管理流程。
这类问题的典型表现是：本地开发一切正常，但一旦执行 git checkout feature/login 或 git switch main 切换分支后，运行 npm run dev 或 yarn build 立即报错：
Module not found: Error: Can't resolve 'react-redux' in '.../src/components' Module not found: Error: Can't resolve '@reduxjs/toolkit' in '.../store'
即使你确认已全局安装过这些包、甚至刚执行过 npm install，错误仍反复出现——尤其在将项目从旧电脑克隆到新环境后首次遇到。
? 根本原因：
node_modules 文件夹被意外提交到了 Git 仓库中。当你在不同分支上开发时，若各分支的 .gitignore 不统一，或历史提交中已包含 node_modules/，Git 在切换分支时会强制覆盖整个 node_modules 目录（包括 package-lock.json 和实际的依赖文件）。这导致：
- 当前分支所需的依赖版本被旧分支的 node_modules 覆盖；
- package-lock.json 与实际 node_modules 不一致；
- 模块解析路径失效，Webpack/Vite 找不到已安装的包。
✅ 正确解决方案（三步到位）：
-
立即添加 node_modules 到 .gitignore（如果尚未存在）：
echo "node_modules/" >> .gitignore
然后提交该修改：
git add .gitignore git commit -m "chore: ignore node_modules"
-
彻底清除已提交的 node_modules（关键！）：
# 从 Git 缓存中移除（不删除本地文件） git rm -r --cached node_modules # 提交清理记录 git commit -m "fix: remove node_modules from version control" # 推送变更（确保团队同步） git push
-
标准化本地初始化流程（每次克隆后必做）：
git clone
cd your-project npm install # 或 yarn / pnpm install npm run dev ✅ 此后所有分支切换均不再触发模块丢失——因为 node_modules 完全由本地 package.json + package-lock.json 决定，与 Git 分支无关。
⚠️ 额外注意事项：
- 检查 package-lock.json 是否被忽略：它必须提交，否则无法保证依赖一致性；
- 若使用 pnpm/yarn，还需确保 .pnpmfile.cjs 或 .yarnrc.yml 等配置文件已纳入版本控制；
- 避免 npm install --save-dev 后忘记提交 package.json 和 package-lock.json；
- 团队协作时，建议在 README.md 中明确标注：“请勿手动修改或提交 node_modules/”。
通过以上操作，你将一劳永逸地告别分支切换引发的模块解析失败问题——让 Git 专注代码版本管理，让包管理器专注依赖安装。
