更新构建文档和 GitHub Actions 工作流，添加 Node.js 和 npm 依赖，优化 Windows 环境设置，确保构建过程的兼容性和可用性。

Author: boybook

.github/workflows/build.yml

@@ -139,31 +139,51 @@ jobs:
             mingw-w64-x86_64-fftw
             mingw-w64-x86_64-boost
             mingw-w64-x86_64-gcc-fortran
+            mingw-w64-x86_64-nodejs
 
-      # 4. 设置 Windows 环境变量和路径
-      - name: Setup Windows environment
+      # 3a. 验证 MSYS2 工具链 - Windows
+      - name: Verify MSYS2 toolchain (Windows)
         if: runner.os == 'Windows'
         shell: msys2 {0}
         run: |
-          # 确保系统 Node.js 和 npm 在 PATH 中
-          export PATH="/c/Program Files/nodejs:$PATH"
-          echo "PATH=/c/Program Files/nodejs:$PATH" >> $GITHUB_ENV
+          echo "=== Verifying MSYS2 toolchain installation ==="
+          echo "Checking essential tools..."
+          which gcc && gcc --version || echo "❌ GCC not found"
+          which g++ && g++ --version || echo "❌ G++ not found"
+          which gfortran && gfortran --version || echo "❌ gfortran not found"
+          which cmake && cmake --version || echo "❌ CMake not found"
+          which pkg-config && pkg-config --version || echo "❌ pkg-config not found"
+          which node && node --version || echo "❌ Node.js not found"
+          which npm && npm --version || echo "❌ npm not found"
+          which npx && npx --version || echo "❌ npx not found"
           
-          # 验证 Node.js 和 npm 是否可用
-          echo "Checking Node.js and npm availability..."
-          which node && node --version
-          which npm && npm --version
-          which npx && npx --version
+          echo "Checking libraries..."
+          pkg-config --exists fftw3f && echo "✅ FFTW3f available" || echo "❌ FFTW3f not found"
+          
+          # Boost 在 MSYS2 中可能没有 pkg-config 文件，检查实际安装
+          if [ -d "/mingw64/include/boost" ]; then
+            echo "✅ Boost headers found"
+          else
+            echo "❌ Boost headers not found"
+          fi
+          
+          if ls /mingw64/lib/libboost* >/dev/null 2>&1; then
+            echo "✅ Boost libraries found"
+          else
+            echo "❌ Boost libraries not found"
+          fi
+          
+          echo "=== Toolchain verification complete ==="
 
-      # 5. 安装 npm 依赖
+      # 4. 安装 npm 依赖
       - name: Install npm dependencies
         run: npm ci --ignore-scripts
 
-      # 6. 构建 TypeScript
+      # 5. 构建 TypeScript
       - name: Build TypeScript
         run: npm run build:ts
 
-      # 7. 构建原生模块 - Linux/macOS
+      # 6. 构建原生模块 - Linux/macOS
       - name: Build native module (Linux/macOS)
         if: runner.os != 'Windows'
         run: |
@@ -186,30 +206,54 @@ jobs:
       # 7. 构建原生模块 - Windows MSYS2/MinGW-w64
       - name: Build native module (Windows MSYS2)
         if: runner.os == 'Windows'
-        shell: cmd
+        shell: msys2 {0}
         run: |
           echo "=== Building with MSYS2/MinGW-w64 toolchain ==="
-          echo "Using system Node.js with MSYS2 MinGW-w64 toolchain"
+          echo "Using improved CMakeLists.txt with MinGW-specific MSVC flag clearing"
           
-          rem 清理构建目录
-          if exist build rmdir /s /q build
+          # 验证工具是否可用
+          echo "Verifying tools availability..."
+          which cmake && cmake --version || echo "CMake not found"
+          which gcc && gcc --version || echo "GCC not found"
+          which gfortran && gfortran --version || echo "gfortran not found"
+          which pkg-config && pkg-config --version || echo "pkg-config not found"
+          which node && node --version || echo "Node.js not found"
+          which npm && npm --version || echo "npm not found"
+          which npx && npx --version || echo "npx not found"
           
-          echo "Starting cmake-js compilation with MinGW Makefiles..."
+          # 设置环境变量强制使用 MinGW 工具链
+          export PKG_CONFIG_PATH="/mingw64/lib/pkgconfig"
+          export CMAKE_PREFIX_PATH="/mingw64"
+          export CC="gcc"
+          export CXX="g++"
+          export FC="gfortran"
+          
+          # 强制 cmake-js 使用 MinGW 而不是 Visual Studio
+          export CMAKE_GENERATOR="MinGW Makefiles"
+          export CMAKE_MAKE_PROGRAM="mingw32-make"
+          
+          # 禁用 Visual Studio 检测
+          unset VSINSTALLDIR
+          unset VCINSTALLDIR
+          unset WindowsSDKDir
+          
+          # 验证 Boost 安装
+          echo "Checking Boost installation..."
+          find /mingw64 -name "*boost*" -type f | head -5
+          ls -la /mingw64/include/boost/ || echo "Boost headers not found"
+          ls -la /mingw64/lib/libboost* | head -3 || echo "Boost libraries not found"
           
-          rem 设置环境变量
-          set "CC=C:/msys64/mingw64/bin/gcc.exe"
-          set "CXX=C:/msys64/mingw64/bin/g++.exe"
-          set "FC=C:/msys64/mingw64/bin/gfortran.exe"
+          # 清理构建目录
+          rm -rf build/
+          
+          echo "Starting cmake-js compilation with MinGW Makefiles..."
+          echo "CMakeLists.txt now handles MSVC flag clearing automatically"
           
-          rem 使用 MinGW Makefiles 生成器构建
-          npx cmake-js compile --arch=${{ matrix.cmake_arch }} ^
-            -- -G "MinGW Makefiles" ^
-            -DCMAKE_C_COMPILER=C:/msys64/mingw64/bin/gcc.exe ^
-            -DCMAKE_CXX_COMPILER=C:/msys64/mingw64/bin/g++.exe ^
-            -DCMAKE_Fortran_COMPILER=C:/msys64/mingw64/bin/gfortran.exe ^
-            -DCMAKE_MAKE_PROGRAM=C:/msys64/mingw64/bin/mingw32-make.exe ^
-            -DPKG_CONFIG_EXECUTABLE=C:/msys64/mingw64/bin/pkg-config.exe ^
-            --verbose
+          # 使用 cmake-js，依赖 CMakeLists.txt 中的修复
+          npx cmake-js compile --arch=${{ matrix.cmake_arch }} \
+            --generator="MinGW Makefiles" \
+            --verbose \
+            -DCMAKE_SHARED_LINKER_FLAGS=\"\"
 
       # 8. 运行测试
       - name: Run tests

BUILD.md

@@ -40,12 +40,11 @@ pacman -S --needed \
   mingw-w64-x86_64-pkg-config \
   mingw-w64-x86_64-fftw \
   mingw-w64-x86_64-boost \
-  mingw-w64-x86_64-gcc-fortran
+  mingw-w64-x86_64-gcc-fortran \
+  mingw-w64-x86_64-nodejs
 ```
 
-**注意**：在 GitHub Actions 中，我们使用系统安装的 Node.js 配合 MSYS2 的编译工具链。如果在本地开发，你可以选择：
-1. 在 MSYS2 中安装 Node.js：`pacman -S mingw-w64-x86_64-nodejs`
-2. 或者使用系统 Node.js 配合 MSYS2 编译工具
+**注意**：npm 随 Node.js 一起安装，无需单独安装。为了确保最佳兼容性，建议使用 MSYS2 版本的 Node.js。
 
 ## 构建步骤
 
@@ -103,19 +102,24 @@ npm run test:full
    - 检查环境变量 PATH 中没有 Visual Studio 的路径干扰
    - 使用 `cmake-js compile -- -G "MinGW Makefiles"` 显式指定生成器
 
-2. **找不到 gfortran**
+2. **链接错误：`cannot find /DELAYLOAD:NODE.EXE`**
+   - 这是 cmake-js 的已知问题，它会为 MinGW 注入 MSVC 专用的链接器标志
+   - 本项目的 CMakeLists.txt 已自动处理此问题，使用 `CACHE FORCE` 清空相关标志
+   - 如果仍有问题，确保使用的是最新版本的项目代码
+
+3. **找不到 gfortran**
    - 确保安装了 `mingw-w64-x86_64-gcc-fortran`
    - 运行 `which gfortran` 验证编译器路径
 
-3. **Node.js 头文件找不到**
+4. **Node.js 头文件找不到**
    - 使用 MSYS2 安装的 Node.js：`pacman -S mingw-w64-x86_64-nodejs`
    - 或确保系统 Node.js 安装正确
 
-4. **pkg-config 找不到库**
+5. **pkg-config 找不到库**
    - 确保 PKG_CONFIG_PATH 包含 MSYS2 路径：`export PKG_CONFIG_PATH="/mingw64/lib/pkgconfig"`
    - 验证库是否正确安装：`pkg-config --list-all | grep fftw`
 
-5. **npx 命令找不到**
+6. **npx 命令找不到**
    - 如果使用系统 Node.js，确保 npm 全局安装目录在 PATH 中
    - 或在 MSYS2 中安装 Node.js：`pacman -S mingw-w64-x86_64-nodejs`
 

CMakeLists.txt

@@ -17,29 +17,55 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 # Enable position independent code for all targets (including subprojects)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
-# Force avoid MSVC detection on Windows when using MinGW
-if(WIN32 AND MSVC)
-    message(FATAL_ERROR "MSVC compiler detected. This project requires MinGW-w64. Please use MSYS2/MinGW-w64 environment and specify -G \"MinGW Makefiles\"")
+# Include cmake-js - this must come first to get CMAKE_JS_* variables
+if(CMAKE_JS_INC)
+    include_directories(${CMAKE_JS_INC})
+endif()
+
+# **关键修复**: 强制清空 cmake-js 通过命令行注入的 MSVC 缓存标志
+# cmake-js 会通过 -DCMAKE_SHARED_LINKER_FLAGS="/DELAYLOAD:NODE.EXE" 注入缓存
+# 必须使用 CACHE FORCE 来覆盖命令行传入的缓存值
+if(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+    message(STATUS "Detected MinGW-w64 on Windows; FORCE-clear CMAKE_SHARED_LINKER_FLAGS from cache")
+    set(CMAKE_SHARED_LINKER_FLAGS "" CACHE STRING "Cleared MSVC-specific linker flags for MinGW compatibility" FORCE)
 endif()
 
-# Windows MinGW-w64 specific setup
-if(WIN32 AND CMAKE_COMPILER_IS_GNUCXX)
+# Add Node.js include path for node_api.h
+execute_process(
+    COMMAND node -p "require('path').dirname(process.execPath) + '/../include/node'"
+    OUTPUT_VARIABLE NODE_INCLUDE_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+include_directories(${NODE_INCLUDE_DIR})
+
+# **关键修复**: Windows + MinGW 环境检测并清除 MSVC 特定标志
+if(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
     message(STATUS "Detected MinGW-w64 environment on Windows")
 
-    # Set PKG_CONFIG_PATH for MSYS2
+    # 设置 PKG_CONFIG_PATH 以便查找 MSYS2 库
     if(EXISTS "C:/msys64/mingw64/lib/pkgconfig")
         set(ENV{PKG_CONFIG_PATH} "C:/msys64/mingw64/lib/pkgconfig")
         message(STATUS "Set PKG_CONFIG_PATH to C:/msys64/mingw64/lib/pkgconfig")
     endif()
 
-    # Add MSYS2 library and include paths
+    # 添加 MSYS2 的 include 和 library 路径
     if(EXISTS "C:/msys64/mingw64")
         include_directories("C:/msys64/mingw64/include")
         link_directories("C:/msys64/mingw64/lib")
         message(STATUS "Added MSYS2 include and library paths")
     endif()
 endif()
 
+# Force avoid MSVC detection on Windows when using MinGW
+if(WIN32 AND MSVC)
+    message(FATAL_ERROR "MSVC compiler detected. This project requires MinGW-w64. Please use MSYS2/MinGW-w64 environment and specify -G \"MinGW Makefiles\"")
+endif()
+
+# Additional check for cmake-js on Windows - prevent Visual Studio generator
+if(WIN32 AND CMAKE_GENERATOR MATCHES "Visual Studio")
+    message(FATAL_ERROR "Visual Studio generator detected. This project requires MinGW-w64. Please set CMAKE_GENERATOR=MinGW Makefiles")
+endif()
+
 # Set compiler flags for better compatibility
 if(UNIX AND NOT APPLE)
     # Linux specific flags
@@ -78,19 +104,6 @@ elseif(WIN32)
     endif()
 endif()
 
-# Include cmake-js
-if(CMAKE_JS_INC)
-    include_directories(${CMAKE_JS_INC})
-endif()
-
-# Add Node.js include path for node_api.h
-execute_process(
-    COMMAND node -p "require('path').dirname(process.execPath) + '/../include/node'"
-    OUTPUT_VARIABLE NODE_INCLUDE_DIR
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-include_directories(${NODE_INCLUDE_DIR})
-
 # Use pkg-config for all platforms (including Windows with MSYS2)
 find_package(PkgConfig REQUIRED)
 
@@ -99,9 +112,39 @@ if(POLICY CMP0167)
     cmake_policy(SET CMP0167 NEW)
 endif()
 
-# Find Boost
-find_package(Boost REQUIRED)
-set(BOOST_LIBRARIES ${Boost_LIBRARIES})
+# Find Boost - use different methods based on platform
+if(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+    # Windows with MinGW-w64: try both find_package and manual detection
+    find_package(Boost QUIET)
+    if(NOT Boost_FOUND)
+        # Manual detection for MSYS2 Boost
+        message(STATUS "Boost not found via find_package, trying manual detection...")
+        
+        # Look for Boost in MSYS2 locations
+        find_path(Boost_INCLUDE_DIRS 
+            NAMES boost/version.hpp
+            PATHS /mingw64/include C:/msys64/mingw64/include
+            NO_DEFAULT_PATH
+        )
+        
+        if(Boost_INCLUDE_DIRS)
+            message(STATUS "Found Boost headers at: ${Boost_INCLUDE_DIRS}")
+            set(Boost_FOUND TRUE)
+            # For header-only libraries, we don't need to link anything
+            set(BOOST_LIBRARIES "")
+        else()
+            message(WARNING "Boost headers not found")
+            set(BOOST_LIBRARIES "")
+        endif()
+    else()
+        message(STATUS "Boost found via find_package: ${Boost_VERSION}")
+        set(BOOST_LIBRARIES ${Boost_LIBRARIES})
+    endif()
+else()
+    # Other platforms: use standard find_package
+    find_package(Boost REQUIRED)
+    set(BOOST_LIBRARIES ${Boost_LIBRARIES})
+endif()
 
 # Find FFTW3 using pkg-config
 pkg_check_modules(FFTW3F REQUIRED fftw3f)
@@ -270,11 +313,27 @@ link_directories(${FFTW3F_LIBRARY_DIRS})
 # Source files for the Node.js addon
 file(GLOB_RECURSE NATIVE_SOURCES "native/*.cpp" "native/*.h")
 
-# Create the Node.js addon
-add_library(${PROJECT_NAME} SHARED 
-    ${NATIVE_SOURCES}
-    ${CMAKE_JS_SRC}
-)
+# Create the Node.js addon with MinGW-specific handling
+if(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+    # MinGW build: exclude Windows delay load hook
+    add_library(${PROJECT_NAME} SHARED 
+        ${NATIVE_SOURCES}
+    )
+    message(STATUS "MinGW build: excluding CMAKE_JS_SRC (Windows delay load hook)")
+else()
+    # Other platforms: include CMAKE_JS_SRC if available
+    if(CMAKE_JS_SRC)
+        add_library(${PROJECT_NAME} SHARED 
+            ${NATIVE_SOURCES}
+            ${CMAKE_JS_SRC}
+        )
+        message(STATUS "Non-MinGW build: including CMAKE_JS_SRC for delay-load hook")
+    else()
+        add_library(${PROJECT_NAME} SHARED 
+            ${NATIVE_SOURCES}
+        )
+    endif()
+endif()
 
 # Set properties for Node.js addon
 set_target_properties(${PROJECT_NAME} PROPERTIES 
@@ -298,9 +357,15 @@ target_compile_definitions(${PROJECT_NAME} PRIVATE
 # Add compile flags
 target_compile_options(${PROJECT_NAME} PRIVATE ${FFTW3F_CFLAGS_OTHER})
 
-# Link libraries
-if(CMAKE_JS_LIB)
-    target_link_libraries(${PROJECT_NAME} PRIVATE ${CMAKE_JS_LIB})
+# Link libraries with MinGW-specific handling
+if(WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+    # MinGW: don't link CMAKE_JS_LIB as it may cause issues
+    message(STATUS "MinGW build: skipping CMAKE_JS_LIB linking")
+else()
+    # Other platforms: link CMAKE_JS_LIB if available
+    if(CMAKE_JS_LIB)
+        target_link_libraries(${PROJECT_NAME} PRIVATE ${CMAKE_JS_LIB})
+    endif()
 endif()
 
 target_link_libraries(${PROJECT_NAME} PRIVATE