Node.js24.20.0 (LTS)

Node.js 的安装完成，只代表系统里出现了一个运行时；真正可复现的开发环境还要固定版本路线、PATH、npm 依赖和模块解释方式。本文以跨平台项目为目标，先选 LTS 或 Current，再验证命令、初始化项目、处理 CommonJS/ESM，最后给出多版本升级的排错顺序。命令示例只说明应执行的检查，不代表本机已经安装。

先按维护周期选择版本

Node.js 官方版本策略将大版本分为 Current、Active LTS、Maintenance LTS 等阶段。项目已有 engines、CI 镜像或托管平台限制时先遵循项目声明；新项目没有约束时，优先从 LTS 开始。

安装前把系统与架构对齐

• Windows、macOS 和 Linux 都有官方预构建版本，但 x64、ARM64、Docker 和系统包管理器不是同一个结果。
• Apple silicon、Windows ARM64 或 Linux ARM64 设备不要盲选 x64；带原生模块的项目还要检查预编译支持。
• 只维护一个版本时可使用官方安装器；多个项目需要不同大版本时，使用团队认可的版本管理工具，避免覆盖系统目录。

把安装来源写进项目记录

记录操作系统、架构、Node.js 版本、npm 版本和安装方式。这样出现“终端能跑、CI 不能跑”时，可以先比较环境，而不是先删除整个项目。

装完立即做三项验证

node --version
npm --version
node -e "console.log(process.version)"

1. 重新打开终端，确认 node 与 npm 都能从当前 PATH 找到。
2. 比较输出是否符合项目要求；如果命中另一套版本管理器，不要马上重复安装。
3. 用最小脚本确认运行时能执行 JavaScript，再进入框架或 Web 服务器配置。

命令找不到时检查终端是否在安装前已打开、安装目录是否加入 PATH，以及当前 shell 是否加载了另一套 Node.js。必要时在 Windows 使用系统的应用执行别名或版本管理器诊断，但不要只看安装程序最后一页。

项目依赖放在本地清单

package.json、lockfile 和 node_modules 各司其职

1. 创建独立项目目录并运行 npm init -y。
2. 用 npm install 包名 添加运行时依赖，用 npm install --save-dev 包名 添加开发依赖。
3. 把启动、测试和构建命令写入 scripts，让本机和 CI 使用同一入口。
4. 提交依赖变更时同时检查 lockfile，不要只提交 package.json。

提前确定 CommonJS 还是 ESM

• package.json 设置 "type": "module" 时，.js 默认按 ESM 解释，可使用 import/export。
• 设置 "type": "commonjs" 或不设置时，.js 通常按 CommonJS 处理，常见 require()。
• .mjs 固定为 ESM，.cjs 固定为 CommonJS；混合旧代码时显式扩展名更容易排错。

模块格式是项目级约定，应与测试、构建脚本和部署环境保持一致。不要因为安装成功就推断 import/require 一定可以互换。

升级多版本时保留可回退点

1. 记录本机、CI 和生产环境的 node --version、npm --version。
2. 检查 package.json 的 engines、CI 镜像和容器标签是否一致。
3. 在干净目录安装，区分 lockfile 变化和旧 node_modules 残留。
4. 涉及原生模块时核对操作系统、架构和编译工具链，再决定是否升级。
5. 先在测试环境跑测试、构建和启动检查，再把 LTS 大版本升级带入生产。

官方当前下载页显示 v24.20.0 为 Latest LTS（2026-08-26），同时列出 v26.8.1 Current；具体补丁版本会继续变化。把版本、依赖和启动命令写成项目记录，才是 Node.js 安装配置教程的可复用结果。