✅ 项目跨平台启动排查 Checklist（适用于 Windows / macOS / WSL）
📦 一、依赖管理
删除本地缓存依赖文件：
rm -rf node_modules package-lock.json
重新安装依赖：
npm install
确认依赖版本一致性：
保证
package.json和package-lock.json中的核心依赖（如react、redux）一致查看模块联邦（Module Federation）中是否存在
singleton模块未对齐：
npm ls redux
避免使用旧缓存：
如果使用的是
pnpm，推荐开启 strict peerDeps可以尝试
npm dedupe做依赖合并
🛠️ 二、构建与编译
清理构建产物：
rm -rf dist .cache
启动构建脚本时使用 WSL 原生 Node 环境，而非被挂载的 Windows 版本：
which node # 确保路径为 /home/xxx/.nvm/...，而非 /mnt/c/...
检查 Webpack 编译输出是否完整，是否有文件未被写入（如：main.js / chunk.js）
🌐 三、服务启动 / 浏览器访问
检查 DevServer 的监听地址是否为 0.0.0.0（否则外部访问不到）：
devServer: {
host: '0.0.0.0',
port: 8000,
}如果是 WSL 环境：
浏览器访问
https://localhost:8000（或https://wsl.localhost:8000）或通过 IP 访问，如
https://172.xxx.xxx.xxx:8000（需关闭防火墙或开启网络桥接）
🔁 四、模块导入与运行时异常
检查是否有
undefined组件渲染：import/export 混淆（
defaultvsnamed）实际文件不存在、路径大小写不一致（Windows 忽略大小写，WSL 区分）
React 报错
type is invalid多半是：清除浏览器缓存或使用无痕模式访问
⚙️ 五、Node/V8 内存设置
避免因 Webpack 编译占用内存闪退：
export NODE_OPTIONS="--max-old-space-size=16384"
可写入 ~/.bashrc 或 .env 文件中自动加载
验证内存生效：
node -e "console.log(v8.getHeapStatistics().heap_size_limit / 1024 / 1024 + ' MB')"
🧩 六、Monorepo 特别注意项
子包之间是否正确构建、依赖（先构建 service/controller，再启动 view）
shared 模块的依赖版本要明确定义，例如：
"overrides": {
"react": "^18.2.0",
"redux": "^4.2.1"
}🚨 七、错误输出关注重点
| 报错信息 | 含义与排查方向 |
|---|---|
type is invalid | 导出组件不正确、路径大小写问题 |
redux unsatisfied version | 模块联邦共享模块版本不一致 |
heap out of memory | Node/V8 内存不足，需手动扩容 |
localhost 无法访问 | DevServer 未监听 0.0.0.0 或防火墙阻断 |
Module not found | 构建产物缺失、webpack 配置或路径拼写错误 |
📌 建议规范（长期）
团队统一使用
nvm管理 Node 版本建议采用
pnpm管理 Monorepo，提高依赖稳定性跨平台开发建议采用 WSL + VSCode Remote 开发模式，确保一致性
提交代码前执行：
npm run clean && npm install && npm run build
付豪
发表评论