Ubuntu 下进行 Node.js 跨平台开发的关键注意事项
一 路径与文件系统
- 使用 path.join / path.resolve 进行路径拼接，避免手写斜杠；ESM 中获取目录请使用 import.meta.url + fileURLToPath + dirname，不要依赖字符串拼接的 __dirname。示例：
- ESM：import { fileURLToPath } from ‘url’; import { dirname, join } from ‘path’; const __dirname = dirname(fileURLToPath(import.meta.url));
- 统一行尾符：读写文本时显式指定 \n 或使用 os.EOL；需要规范化内容时用正则 /\r?\n/g 替换，避免跨平台换行导致校验或解析失败。
- 注意 Windows 长路径限制（MAX_PATH 260）：深层嵌套或长文件名可能触发 ENAMETOOLONG；尽量缩短路径层级，必要时启用长路径前缀或迁移到更短的工作区目录。
二 环境变量与 npm 脚本
- 在 npm scripts 中设置或传递环境变量时，使用 cross-env 统一语法，避免 Windows 与类 Unix 的语法差异（如 $VAR 与 %VAR%）。
- 访问变量用 process.env；创建子进程时通过 child_process 的 env 选项显式传参，避免依赖外部环境的不确定性。
- 注意大小写：Windows 环境变量不区分大小写（msys 除外），而 Unix 区分；跨平台时应统一命名规范，必要时做映射或校验。
- 常见系统变量映射与获取方式：
- 家目录：HOME ↔ USERPROFILE，代码用 os.homedir()；
- 临时目录：TMPDIR ↔ TMP/TEMP，代码用 os.tmpdir()；
- 主机名：HOSTNAME ↔ COMPUTERNAME，代码用 os.hostname()。
三 操作系统识别与条件逻辑
- 基础识别用 process.platform：返回 ‘win32’ / ‘linux’ / ‘darwin’（Windows 上 64 位也返回 ‘win32’）；需要更细信息时再用 os.type() / os.release() / os.version() / os.arch()。
- 典型用法模板：
- 路径前缀：const base = process.platform === ‘win32’ ? ‘C:\Program Files’ : ‘/usr/local’;
- 命令适配：根据平台选择不同的可执行文件或参数；
- 架构分支：如 os.arch() 为 ‘arm64’ 时启用对应二进制或优化路径。
四 原生模块与构建链
- 使用 node-gyp 构建原生插件时，各平台需准备对应工具链：
- Windows：安装 Python 与 Visual Studio 构建工具（如 VS2022 的 VC++ 工作负载）；
- macOS：安装 Xcode 命令行工具；
- Ubuntu/Debian：安装 python3 make gcc g++。
- 多 Python 版本并存时，可通过命令行 –python 或环境变量 npm_config_python 指定解释器路径，减少构建不确定性。
五 版本管理与内存配置
- 用 nvm / nvm-windows 管理多版本 Node；在项目中加入 .nvmrc 与 package.json engines 字段，明确版本约束，避免“在我机器上能跑”的问题。
- 大型构建/打包出现内存不足时，通过 NODE_OPTIONS=–max-old-space-size=4096 提升堆上限；在 npm scripts 中结合 cross-env 统一设置，确保跨平台生效。