Linux 上部署 Node.js 项目:从环境准备到 Nginx 反向代理的完整流程

Felix
Felix
发布时间:2026-08-23| 44人浏览过
原创

前言

把 Node.js 项目部署到 Linux,真正容易出问题的往往不是某一条命令,而是环境、进程、反向代理和安全配置之间有没有接上。下面按实际部署顺序梳理一遍,从服务器准备到 Nginx 转发,再到 PM2 常驻和基础加固,方便你快速判断每一步该做到什么程度。

把 Node.js 项目部署到 Linux,真正容易出问题的往往不是某一条命令,而是环境、进程、反向代理和安全配置之间有没有接上。下面按实际部署顺序梳理一遍,从服务器准备到 Nginx 转发,再到 PM2 常驻和基础加固,方便你快速判断每一步该做到什么程度。

这套流程适合大多数中小型项目起步使用。你可以直接照着命令执行,也可以把它当成部署检查清单:项目为什么跑不起来、为什么域名打不开、为什么终端一断应用就停,基本都能在对应章节里找到原因和处理方式。

准备服务器运行环境

在上传项目之前,先确认 Linux 服务器具备 Node.js 的运行和构建能力。至少要有 Node.js、npm,如果项目依赖原生扩展,还需要安装编译工具链。

如果服务器还没安装 Node.js,可以直接使用文中的方式安装:

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs

有些依赖在安装时会调用 C/C++ 编译工具,因此建议一并安装 build-essential:

sudo apt-get install build-essential

这一步的目标很明确:让服务器既能运行应用,也能顺利完成 npm install 期间的依赖编译。

把项目代码上传到服务器

环境就绪后,下一步是把本地项目传到服务器。常见方法包括 FTP、SCP 和 rsync;如果是体量不大的项目,直接用 SCP 就够了。

scp -r 你的项目目录 用户名@服务器IP:/目标路径

上传完成后,建议立即登录服务器检查目录结构是否完整,尤其注意配置文件、静态资源和构建脚本有没有遗漏。很多“部署失败”其实只是代码没传全,或者上传路径与后续操作路径不一致。

安装依赖并配置环境变量

先完成项目依赖安装

进入项目目录后,先执行依赖安装命令:

npm install

这条命令会读取 package.json 并安装项目所需依赖。如果安装过程中遇到权限问题,可以尝试:

npm install --unsafe-perm

原文也提到,另一种更稳妥的做法是尽量使用普通用户操作,减少因权限混乱导致的后续问题。

把敏感配置移到环境变量

数据库连接串、API 密钥这类信息不适合直接写在代码里。更常见的做法,是在服务器环境中单独配置。

例如可以在 ~/.bashrc 或 ~/.bash_profile 中加入:

export NODE_ENV=production
export DATABASE_URL=mongodb://user:password@host:port/dbname

保存后执行:

source ~/.bashrc

如果你希望项目配置更集中,也可以把变量写到项目根目录的 .env 文件中,再配合 dotenv 包自动加载。这样在多环境切换时通常会更灵活,但前提是要保护好 .env 文件本身,不要误提交到仓库。

启动应用并用 PM2 保持常驻

测试应用最直接的方式是运行:

展示 Linux 上 Node.js 项目从环境准备到常驻运行的部署步骤信息图
Node.js 部署前半程流程图把部署流程拆成环境、代码、依赖、变量和进程管理五个连续环节,更容易定位问题出在哪一步。
node app.js

但这种方式只适合临时验证。只要当前终端退出,进程就会停止,服务也随之中断。

要让 Node.js 应用长期稳定运行,更实用的方案是使用 PM2:

npm install pm2 -g
pm2 start app.js --name "my-app"

PM2 能解决几个部署阶段最常见的问题:进程退出后自动重启、日志集中管理,以及在需要时进行负载均衡。对个人项目和中小型服务来说,这已经能覆盖大部分基础运维需求。

如果还希望服务器重启后应用自动恢复,可以继续执行 pm2 startup 生成系统服务配置。这样应用就不会依赖你手动重新登录启动。

配置 Nginx 反向代理对外提供访问

Node.js 应用通常监听的是类似 3000 这样的内部端口,但实际对外提供服务时,往往需要通过 80 或 443 端口访问。这时通常会在前面加一层 Nginx 作为反向代理。

展示 Nginx 反向代理到本地 Node.js 端口以及上线后安全监控要点的信息图
对外访问与基础运维结构对外访问并不直接连到 Node.js 进程,而是先经过 Nginx,再配合防火墙、HTTPS。

一个常见配置如下:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

将配置保存到 /etc/nginx/sites-available/example.com,再创建到 sites-enabled 的符号链接:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

这里有三个检查点值得注意:

  • Nginx 配置文件路径是否正确;
  • proxy_pass 指向的端口是否与 Node.js 应用实际监听端口一致;
  • sudo nginx -t 是否通过语法检查。

只要这几项没有问题,重启 Nginx 后,应用一般就可以通过域名正常访问。

补上安全加固和基础监控

应用能跑起来,只是部署完成的一半。真正上线时,还需要至少补齐防火墙、HTTPS 和运行状态监控。

原文给出的建议包括:

  • 使用 ufw 配置防火墙,只开放必要端口;
  • 安装 SSL 证书,优先考虑 Let's Encrypt,让站点支持 HTTPS;
  • 定期更新系统和依赖包,减少已知漏洞风险。

监控方面,如果项目规模不大,可以先用 PM2 自带能力查看资源占用:

pm2 monit

如果后续需要更完整的告警、链路追踪和指标分析,再考虑接入 New Relic、Datadog 这类专业方案。对于很多小型 Node.js 服务来说,先把 PM2 监控和日志管理用起来,已经能覆盖最基础的线上观察需求。

部署完成后,重点检查什么

如果你已经按顺序完成了操作,最后可以回头做一遍快速核对:

  • 服务器是否已经安装 Node.js、npm 和 build-essential;
  • 项目文件是否完整上传到目标路径;
  • npm install 是否成功执行;
  • NODE_ENV、数据库连接等环境变量是否已经生效;
  • 应用是否由 PM2 管理,而不是依赖前台终端运行;
  • Nginx 是否成功将域名请求转发到 Node.js 监听端口;
  • 防火墙、HTTPS 和基础监控是否已经补齐。

掌握这几个环节后,Linux 上部署 Node.js 项目就不再只是“能跑起来”,而是具备了一个可持续使用的基础上线形态。后续无论是继续接数据库、处理静态资源,还是做日志切割与性能优化,都会更顺手。

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。