前端项目跨平台启动排查 CheckList

✅ 项目跨平台启动排查 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 混淆（default vs named）

• 实际文件不存在、路径大小写不一致（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"
}

🚨 七、错误输出关注重点

📌 建议规范（长期）

• 团队统一使用 nvm 管理 Node 版本

• 建议采用 pnpm 管理 Monorepo，提高依赖稳定性

• 跨平台开发建议采用 WSL + VSCode Remote 开发模式，确保一致性

• 提交代码前执行：

npm run clean && npm install && npm run build