根本原因是vscode默认不识别napi-rs生成的.node文件为可调试目标，且launch.json常漏配env、sourcemaps及调试符号路径；必须启用debug构建、显式设置node_options="--enable-source-maps"、正确配置outfiles指向pkg/目录，并确保rust调试符号文件存在。
为什么 napi-rs 在 VSCode 里跑不起来调试？
根本原因不是 Rust 或 Node 不兼容，而是 VSCode 默认不识别 napi-rs 生成的 .node 文件为可调试目标，且 launch.json 配置容易漏掉 env 和 sourceMaps 关键项。
- Rust 编译产物（如
index.node）本质是动态链接库，Node 进程加载它时不会自动触发源码映射 —— 必须显式开启sourceMap: true并确保debug模式编译 -
napi-rs默认用releaseprofile 构建，关掉了调试符号；调试前必须改用cargo build --debug或在Cargo.toml中启用debug = true - VSCode 的 Node 调试器默认不继承
LD_LIBRARY_PATH（Linux/macOS）或PATH（Windows），导致找不到 Rust 运行时依赖，需手动注入
launch.json 怎么配才能进 Rust 断点？
不能只靠 type: "pwa-node"，得把 Rust 和 Node 的调试上下文真正串起来。关键在于三件事：启动 Node 时加载调试版 .node、让 VSCode 找到 Rust 源码、绕过 V8 对原生模块的符号忽略。
- 确保
program指向你的入口 JS 文件（如test.js），不是.node文件本身 - 必须加
"env": { "NODE_OPTIONS": "--enable-source-maps" }，否则 V8 不解析.map文件 -
"sourceMaps": true和"outFiles": ["./pkg/**/*.js", "./pkg/**/*.map"]要成对出现；napi-rs输出目录默认是pkg/，别写成dist/ - Windows 下额外加
"env": { "PATH": "${workspaceFolder}/target/debug;${env:PATH}" }，Linux/macOS 则用LD_LIBRARY_PATH
怎么验证 Rust 断点真被命中？
光在 lib.rs 里打断点没用 —— VSCode 默认只 attach 到 JS 线程。Rust 断点生效的前提是：Node 进程已加载模块，且调试器能定位到 target/debug/*.dSYM（macOS）或 *.pdb（Windows）或 *.debug（Linux）。
- 运行
napi build --debug后检查target/debug/是否存在同名.so/.dll/.dylib文件及对应调试符号文件 - 在 JS 调用处（如
myNativeFunc()）先打一个 JS 断点，F11 进入后，再切回 Rust 文件设断点 —— 直接设在 Rust 入口函数（如#[napi]标记的函数）上更可靠 - 如果断点变空心圆，说明 VSCode 没读到符号：检查
rustc是否用了-C debuginfo=2（profile.debug默认开启），以及launch.json中outFiles路径是否拼错
常见报错和绕过方法
Error: Cannot find module './index.node' 或 Segmentation fault (core dumped) 这类问题，90% 出在构建与运行环境不一致。
-
Cannot find module：确认pkg/下有index.node，且package.json的"main"字段指向正确路径（如"main": "pkg/index.js"），JS 中require的路径要和index.js导出一致 -
Segmentation fault：大概率是release构建后混用了debug版 Node 或反之；统一用nvm use锁定 Node 版本，并在.cargo/config.toml加[build] target = "x86_64-unknown-linux-gnu"（匹配你的 Node ABI） - Windows 上
LoadLibraryA失败：禁用杀毒软件实时扫描target/目录，或把项目移到非 OneDrive/WSL 跨区路径
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
