整体流程 #

1. 搭建开发所需环境
2. 获取源代码并安装依赖包
3. 在开发服务器上验证运行
4. 创建生产环境构建
5. 配置 Nginx 并发布构建好的文件
6. 配置 HTTPS(如需)
7. 设置重启时自动启动(如需)

以下步骤说明将提供具体的操作示例。

STEP1. 准备开发环境 #

STEP1.1 安装 Node.js 和 npm #

在 Ubuntu 上,可以使用以下命令安装 Node.js 和 npm。

sudo apt update
sudo apt install -y nodejs npm

安装后确认版本。

node -v
npm -v

STEP1.2 准备服务器 #

• 准备 Ubuntu 等 Linux 服务器,确保可以通过 SSH 登录。
• (因为是生产环境运行的前提)请准备具有 root 或 sudo 权限的用户。

STEP2. 获取源代码 #

STEP2.1 下载/克隆源代码 #

• 如果源代码在 GitHub 等平台上,使用 git clone https://... 获取
• 如果是 Zip 文件,上传后解压
• 以下假设源代码放置在 /home/project

STEP2.2 安装依赖包 #

进入源代码所在目录,使用 npm install 安装所需库文件。

cd /home/project
npm install

成功后会生成 node_modules 目录。

STEP3. 在开发服务器上验证运行 #

开发时使用 npm run dev 在本地启动简易服务器。以下为示例。

npm run dev

执行后终端会显示类似 Local: http://localhost:5173 的日志。
在浏览器中访问该 URL 即可确认应用正在运行。

• 如需在远程服务器上测试,请在 vite.config.ts 中将 server.host 设置为 0.0.0.0,以允许外部访问。

STEP4. 创建生产环境构建 #

开发完成后,创建生产环境构建。这是优化应用并在 dist 目录中
生成最终静态文件(HTML/JS/CSS)的过程。

cd /home/project
npm run build

• 成功后,会在项目根目录生成 dist 文件夹。
• 其中包含 index.html 和 assets 文件夹等。

STEP5. 使用 Nginx 发布构建好的文件 #

通常不使用 Vite 的预览服务器,而是通过Nginx 等 Web 服务器发布静态文件。

STEP5.1 安装 Nginx #

在 Ubuntu 上安装 Nginx。

sudo apt update
sudo apt install -y nginx

安装后,在浏览器中访问 http://<服务器IP地址>/
会显示”Welcome to nginx!”页面。

STEP5.2 部署生产环境文件 #

1. 创建发布文件夹 (例如: /var/www/myapp)

   sudo mkdir -p /var/www/myapp
   

2. 复制构建好的文件(dist中的内容)

   sudo cp -r /home/project/dist/* /var/www/myapp/
   

3. 部署后,确认内容

   ls -l /var/www/myapp
   # 有 index.html 和 assets 文件夹即可
   

STEP5.3 创建 Nginx 配置文件 #

Nginx 标准的配置管理方式是在 sites-available/ → sites-enabled/
中管理 server { ... } 配置块。

1. 创建新的配置文件

   sudo nano /etc/nginx/sites-available/myapp.conf
   

2. 填写以下内容 (针对 SPA 的配置示例)

   server {
       listen 80;
       server_name _;  # 仅用 IP 访问时。若使用域名则 server_name example.com;
       root /var/www/myapp; # dist文件部署路径
       index index.html;
   
       # SPA 支持配置: 路由路径为 /xxx 时也回退到 index.html
       location / {
           try_files $uri $uri/ /index.html;
       }
   }
   

   • server_name 如使用生产环境域名,例如: server_name example.com;
   • root /var/www/myapp; 指定构建文件的部署目录
   • try_files $uri $uri/ /index.html; 用于支持 React Router 等,即使直接输入 URL 也会回退到 index.html
3. 启用配置文件并禁用默认配置

   # 通过符号链接将 myapp.conf 放入 sites-enabled
   sudo ln -s /etc/nginx/sites-available/myapp.conf /etc/nginx/sites-enabled/
   
   # 如有默认站点则禁用
   sudo rm /etc/nginx/sites-enabled/default
   

4. nginx 配置文件的语法检查 & 重新加载

   sudo nginx -t
   sudo systemctl reload nginx
   

5. 在浏览器中访问 http://<服务器IP>/
   • 如果显示的不是之前的”Welcome to nginx!”，而是构建后的应用，则表示成功。

STEP6. 引入 HTTPS (SSL)（根据需要） #

在生产环境中，通常需要支持 https://。
使用免费的 Let’s Encrypt (Certbot) 的示例：

sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

按照交互式提示进行操作后，nginx 会自动配置 SSL 设置，从而可以通过 HTTPS 访问。
（需要将 DNS 的 yourdomain.com 指向此服务器）

STEP7. 重启时的自动启动 #

STEP7.1 仅静态文件的情况 #

如果是 nginx 分发通过 Vite 构建的静态文件，
只要nginx 设置为自动启动就没有问题。请确认是否已完成以下设置。

sudo systemctl enable nginx

这样服务器重启时也会自动启动 nginx。

STEP7.2 存在 Node.js + Express / API服务器的情况 #

如果需要后端 Node.js，并在同一服务器上运行，通常使用 PM2 或 systemd 使 Node.js 进程常驻化。

# 安装 PM2
sudo npm install -g pm2

# 启动应用（Express等）
pm2 start "npm run start" --name my-backend

# 启用自动启动
pm2 startup systemd
pm2 save

nginx 只将对 /api/ 的请求通过 proxy_pass 转发到 Node.js，
前端则通过静态文件分发，形成这样的架构。

STEP8. 故障排查 #

1. 仍然显示”Welcome to nginx!”
   • 未禁用默认配置
   • server_name 不匹配
2. 出现 404 错误
   • root 设置的路径有误
   • SPA 未设置 try_files
3. 浏览器无法访问
   • 未开放端口 80/443（云服务的安全组或 UFW）
   • 服务器 IP 或域名未正确分配

STEP9. 总结 #

1. 开发：使用 npm run dev 确认运行
2. 构建：npm run build → 生成 dist 文件夹
3. 使用 nginx 分发：将 dist 中的内容放置到 /var/www/myapp → 设置 myapp.conf → nginx -t → systemctl reload nginx
4. 支持 HTTPS：通过 certbot --nginx -d yourdomain.com 等方式获取证书
5. 自动启动：如果只有静态文件则使用 nginx，如果需要自建 API 则使用 PM2 或 systemd 管理 Node.js 常驻进程