Node.js 在 Windows Server 上的离线部署方案

Node.js 在 Windows Server 上的离线部署方案

离线部署的核心是提前准备所有依赖资源（避免在线下载），并通过本地配置完成服务搭建，整体分为「依赖准备」「环境配置」「项目部署」「服务注册」4个阶段。

一、提前准备离线资源（关键：在有网机器操作）

需准备 3 类核心资源，确保无网环境下可完整安装：

资源类型	获取方式	注意事项
Node.js 离线安装包	1. 访问 Node.js 官网 2. 选择对应版本（建议 LTS 版，如 20.x） 3. 下载 Windows 离线包（msi 或 zip，优先 msi 自动配置环境变量）	确认 Windows Server 系统架构（32/64 位），下载对应版本。
项目依赖包（node_modules）	1. 在有网机器上，拷贝项目源码到本地 2. 执行 npm install --production（只装生产依赖，减小体积） 3. 压缩生成的 node_modules 文件夹	确保有网机器与 Windows Server 系统架构一致（避免依赖编译后不兼容，如 node-gyp 相关包）。
可选：编译依赖环境	若项目依赖需编译（如 sqlite3 bcrypt），需提前下载： 1. Python 离线安装包 2. Visual Studio Build Tools 离线包	离线安装时，需先装 Python + Build Tools，再解压 node_modules（或执行本地依赖安装）。

二、Windows Server 环境配置（无网机器操作）

1. 安装 Node.js 环境

1. 将下载的 Node.js msi 包拷贝到 Windows Server，双击运行安装；
2. 安装向导中，勾选「Add to PATH」（自动配置环境变量，无需手动改），其余默认下一步；
3. 验证安装：打开「命令提示符（CMD）」，执行以下命令，显示版本即成功：

   node -v  # 如 v20.11.0
   npm -v   # 如 10.2.4
   

   • 若用 zip 包：解压到指定目录（如 D:\Node.js），手动添加 D:\Node.js 和 D:\Node.js\node_global 到「系统环境变量-PATH」，再验证版本。

2. 配置项目目录

1. 在 Windows Server 上创建项目目录（如 D:\NodeProjects\your-app）；
2. 拷贝以下文件到该目录：
   • 项目源码（app.js/server.js 入口文件、package.json、配置文件等）；
   • 提前压缩的 node_modules 文件夹，解压到项目根目录（与 package.json 同级）。

三、项目部署与测试

1. 本地启动测试（验证项目可运行）

1. 打开 CMD，进入项目目录：

   cd D:\NodeProjects\your-app
   

2. 执行启动命令（根据项目入口文件调整，如 app.js）：

   node app.js
   

3. 验证服务：
   • 本地验证：在 Server 上打开浏览器，访问 http://localhost:端口号（如 http://localhost:3000），若返回正常页面/API 结果，说明项目可运行；
   • 局域网验证：在同一局域网机器上，访问 http://Windows Server IP:端口号（如 http://192.168.1.100:3000），确保端口未被防火墙拦截（需开放端口，见下文「故障排查」）。

2. 解决端口占用问题（可选）

若启动时报「端口被占用」，执行以下命令排查并释放：

1. 查看端口占用情况（以端口 3000 为例）：

   netstat -ano | findstr ":3000"
   

2. 找到 PID（最后一列数字），结束对应进程：

   taskkill /F /PID 1234  # 1234 替换为实际 PID
   

四、注册 Windows 服务（实现后台运行+开机自启）

直接用 node app.js 启动后，关闭 CMD 服务会停止，需将 Node 项目注册为 Windows 系统服务，推荐用 pm2（轻量且支持 Windows 服务）。

1. 离线安装 pm2（提前在有网机器准备）

1. 在有网机器上，执行 npm install pm2 -g（全局安装 pm2）；
2. 找到 pm2 安装目录（默认路径：C:\Users\用户名\AppData\Roaming\npm\node_modules\pm2）；
3. 将 pm2 文件夹压缩，拷贝到 Windows Server 的 Node 全局模块目录（默认：C:\Users\用户名\AppData\Roaming\npm\node_modules\），解压覆盖。

2. 用 pm2 管理 Node 服务

1. 进入项目目录，执行启动命令（指定入口文件，如 app.js）：

   pm2 start app.js --name "your-app-name"  # --name 自定义服务名，方便管理
   

2. 验证 pm2 服务状态：

   pm2 list  # 查看服务列表，状态为 "online" 即正常
   

3. 注册为 Windows 系统服务（开机自启）

1. 执行 pm2 服务安装命令：

   pm2-service-install  # 弹出提示，直接按 Enter 确认（默认服务名 PM2）
   

2. 验证系统服务：
   • 打开「控制面板 → 管理工具 → 服务」；
   • 找到「PM2」服务，确认「启动类型」为「自动」，「状态」为「正在运行」。

五、部署验证与故障排查

1. 最终验证

• 重启 Windows Server，检查「PM2」服务是否自动启动；
• 访问 http://Server IP:端口号，确认项目正常响应。

2. 常见问题解决

问题现象	排查方向
服务启动后无法访问	1. 检查端口是否开放（Windows 防火墙 → 高级设置 → 入站规则，添加端口允许） 2. 确认项目监听地址不是 127.0.0.1（需改为 0.0.0.0，允许外部访问）。
依赖报错（如 “module not found”）	1. 检查 node_modules 是否完整（对比有网机器的文件夹大小） 2. 若依赖需编译，确认已安装 Python + Build Tools。
PM2 服务启动失败	1. 查看 PM2 日志：pm2 logs 2. 检查 Windows 事件查看器（「Windows 日志 → 应用程序」），定位错误原因。

总结

离线部署的关键是提前规避“在线依赖”：所有 Node 环境、项目依赖、工具（如 pm2）都需在有网环境打包，再拷贝到 Windows Server；通过 pm2 注册系统服务，确保服务稳定运行且开机自启，最后验证端口和依赖兼容性即可完成部署。