Windows环境下Node.js引入maplibre-gl-native无报错崩溃求助

在Windows环境的Node.js（TypeScript）项目中，只要导入@maplibre/maplibre-gl-native就触发进程无报错崩溃，可尝试以下排查和解决步骤：

• 重新安装并检查依赖完整性
  彻底清理现有依赖后重新安装，避免安装过程中出现的静默失败：

  1. 删除项目根目录的node_modules文件夹、package-lock.json（或yarn.lock）文件
  2. 执行npm install @maplibre/maplibre-gl-native --verbose，查看安装日志中是否有编译警告或错误（Native模块编译失败可能导致后续运行崩溃）

• 验证系统运行时依赖
  @maplibre/maplibre-gl-native作为Native模块，依赖微软Visual C++运行库：

  1. 安装最新版x64架构的Visual C++ Redistributable for Visual Studio 2015-2022
  2. 使用Dependency Walker工具扫描node_modules/@maplibre/maplibre-gl-native/lib/mbgl.node文件，确认不存在缺失的.dll依赖

• 创建极简纯Node.js项目测试
  排除Vite等构建工具的潜在冲突：

  1. 初始化纯Node.js项目：npm init -y
  2. 安装依赖：npm install typescript @types/node @maplibre/maplibre-gl-native
  3. 配置tsconfig.json为CommonJS模块规范（target设为ES2020，module设为CommonJS）
  4. 编写测试文件index.ts：

     import mbgl from "@maplibre/maplibre-gl-native";
     console.log("mbgl模块加载成功:", mbgl);
     

  5. 运行测试：npx ts-node index.ts

• 捕获崩溃日志
  强制Node.js输出崩溃细节，或通过系统日志排查：

  1. 运行项目时添加参数：npx ts-node --abort-on-uncaught-exception --trace-uncaught server.ts（TS项目），或node --abort-on-uncaught-exception --trace-uncaught server.js（JS项目），查看终端输出的崩溃调用栈
  2. 打开Windows「事件查看器」→「Windows日志」→「应用程序」，查找Node.js进程崩溃的事件记录，获取错误代码和详细信息

• 手动编译Native模块
  若自动安装时编译失败，尝试手动编译：

  1. 全局安装node-gyp：npm install -g node-gyp
  2. 确保系统安装了Python 3.8-3.11版本，并配置到环境变量
  3. 进入node_modules/@maplibre/maplibre-gl-native目录，执行node-gyp rebuild，查看编译过程中的错误信息

内容的提问来源于stack exchange，提问作者Andreas