Vite + Node.js 全栈项目从开发到生产部署完整教程

✅ 从零到上线完整全栈实战教程，全覆盖 Vite 前端、Node.js 后端、MySQL 数据库、Git 版本管理、Linux 服务器部署、PM2 进程守护、**Nginx 反向代理（核心重点）**、HTTPS 加密、FRP 内网穿透、项目迭代更新、线上问题排查。配置开箱即用，可直接落地个人/小型商业项目。

*🧩 技术栈全景*：Vite5 + Vue3/React + Node.js(Express) + MySQL8 + Nginx + PM2 + FRP + HTTPS

一、项目整体架构说明

本项目采用标准前后端分离生产****架构，统一部署规范，杜绝本地/环境差异问题：

  • 🖥️ 前端：Vite 极速构建，本地开发调试，生产打包输出纯净 dist 静态目录

  • ⚙️ 后端：Node.js 服务固定监听 3001 端口，全局统一接口前缀 /api/

  • 🔁 代理核心：Nginx 托管 dist 静态资源，/api/ 全局反向代理至本机 3001 端口

  • 🌐 网络方案：公网正式部署 + FRP 内网穿透本地调试 双模式适配

  • 🔒 安全方案：全站 HTTPS 加密，杜绝明文访问风险

二、Vite 前端开发与生产打包

2.1 初始化 Vite 项目

支持 Vue3 / React 主流框架，执行官方标准化初始化命令：

# npm 创建项目
npm create vite@latest frontend

# 进入项目目录
cd frontend

# 安装依赖
npm install

# 本地开发启动
npm run dev

2.2 开发环境接口代理配置

修改项目根目录 vite.config.js，配置本地跨域代理，统一对接后端 /api/ 接口，彻底解决本地开发跨域问题：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      // 匹配所有 /api/ 接口请求
      '/api/': {
        target: 'http://127.0.0.1:3001',
        changeOrigin: true,
        rewrite: (path) => path
      }
    }
  }
})

2.3 生产环境打包（dist 目录）

项目功能开发完成后，执行打包命令，生成生产唯一可用静态资源目录 dist，用于服务器 Nginx 托管部署：

# 生产打包
npm run build

# 打包完成后，根目录会生成 dist 文件夹，为唯一生产前端部署文件

生产关键规范：生产环境禁止使用 Vite 开发服务，全程由 Nginx 托管 dist 静态文件，具备更高访问性能、更强稳定性、更低服务器资源占用。

三、Node.js 后端开发（端口3001）

3.1 后端项目初始化

# 创建后端目录
mkdir backend && cd backend

# 初始化 npm 项目
npm init -y

# 安装核心依赖
npm install express cors mysql2 dotenv
npm install -D nodemon

3.2 基础服务配置（固定3001端口）

新建项目入口文件 app.js，固定服务端口、统一接口前缀，同时编写健康测试接口，方便后续部署验证：

require('dotenv').config()
const express = require('express')
const cors = require('cors')
const app = express()

// 中间件
app.use(cors())
app.use(express.json())

// 测试接口
app.get('/api/hello', (req, res) => {
  res.json({ code: 200, msg: '后端服务部署成功！', data: null })
})

// 监听3001端口
const PORT = 3001
app.listen(PORT, () => {
  console.log(`Node服务运行在 http://127.0.0.1:${PORT}`)
})

module.exports = app

3.3 本地热更新配置

修改 package.json 脚本：

"scripts": {
  "start": "node app.js",
  "dev": "nodemon app.js"
}

本地开发使用热更新启动，无需反复重启服务；生产环境使用原生 node 命令启动，配合 PM2 进程守护。

四、MySQL 数据库初始化

4.1 数据库基础配置

本地、服务器环境通用 SQL 脚本，一键创建项目专属数据库、授权用户，适配 MySQL8.0+ 版本：

# 登录MySQL
mysql -u root -p

# 创建项目数据库
CREATE DATABASE IF NOT EXISTS vite_node_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 创建专属用户（可选）
CREATE USER IF NOT EXISTS 'vite_user'@'%' IDENTIFIED BY '你的数据库密码';

# 授权
GRANT ALL ON vite_node_db.* TO 'vite_user'@'%';
FLUSH PRIVILEGES;

4.2 Node 对接 MySQL 配置

通过 .env 文件统一管理环境变量，区分开发/生产环境，避免硬编码配置，方便后期环境切换：

# 数据库配置
DB_HOST=127.0.0.1
DB_USER=vite_user
DB_PASS=你的数据库密码
DB_NAME=vite_node_db
DB_PORT=3306

# 服务端口
SERVER_PORT=3001

新建数据库连接工具类，封装数据库连接池，提升接口请求效率，避免频繁创建销毁连接：

const mysql = require('mysql2/promise')
require('dotenv').config()

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASS,
  database: process.env.DB_NAME,
  port: process.env.DB_PORT,
  waitForConnections: true,
  connectionLimit: 10
})

module.exports = pool

五、Git 版本管理规范

5.1 初始化仓库

# 项目根目录初始化git
git init

# 配置用户信息
git config user.name "你的用户名"
git config user.email "你的邮箱"

5.2 配置 .gitignore

配置全局忽略文件，过滤依赖、缓存、环境变量、系统垃圾文件，避免敏感文件、无用文件误提交仓库：

# 依赖
node_modules/
.pnp
.pnp.js

# 环境变量
.env
.env.local
.env.production

# 打包缓存
dist/
build/

# 日志与运行文件
logs/
*.log
pm2.lock

# 系统文件
.DS_Store
Thumbs.db

5.3 提交与推送规范

git add .
git commit -m "feat: 项目初始化完成，前后端基础架构搭建"
git remote add origin 你的仓库地址
git push -u origin main

部署建议：dist 打包目录建议不提交远程仓库，服务器部署时直接拉取源码、现场打包，规避本地与服务器环境依赖差异导致的打包报错。

六、Linux 服务器环境准备

适配 CentOS / Ubuntu 主流服务器系统，一键安装项目全部依赖环境：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装nodejs、npm、git、nginx、mysql
sudo apt install nodejs npm git nginx mysql-server -y

# 安装pnpm（可选，加速依赖安装）
npm install -g pnpm

# 安装pm2进程管理
npm install -g pm2

6.2 环境版本验证

node -v
npm -v
nginx -v
pm2 -v
mysql -V

七、PM2 管理 Node.js 后端服务

7.1 项目上传与依赖安装

将后端源码上传至服务器对应目录，安装项目依赖，准备服务启动：

cd /你的项目目录/backend
npm install

7.2 PM2 启动服务

# 启动服务，命名为vite-node-api
pm2 start app.js --name "vite-node-api"

# 设置开机自启
pm2 startup
pm2 save

# 常用命令
pm2 list          # 查看运行服务
pm2 restart all   # 重启所有服务
pm2 stop all      # 停止所有服务
pm2 logs          # 查看运行日志
pm2 delete 服务名  # 删除服务

PM2 核心价值：实现 Node 服务后台常驻、异常崩溃自动重启、运行日志持久化、服务器开机自启，保障 7*24h 生产服务稳定运行。

八、Nginx 反向代理核心配置（重点）

本章为全文核心重点，实现生产环境最关键能力：Nginx 托管前端 dist 静态资源 + /api/ 请求精准反向代理至 3001 端口 Node 后端服务。

8.1 项目部署目录规范

  • 前端静态资源目录：/var/www/vite-project/dist

  • 后端服务运行端口：3001（PM2 常驻托管）

  • Nginx 配置存放路径：/etc/nginx/sites-available/

8.2 Nginx 基础配置文件

新建站点配置文件，包含静态资源托管、路由 404 修复、API 反向代理、静态资源缓存优化全套生产配置：

server {
    listen 80;
    server_name 你的域名;

    # 托管Vite打包的dist静态文件
    root /var/www/vite-project/dist;
    index index.html;

    # 解决Vue/React路由刷新404问题
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 核心：/api/ 反向代理到本地3001端口Node服务
    location /api/ {
        proxy_pass http://127.0.0.1:3001/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 静态资源缓存优化
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

8.3 启用配置并重启Nginx

# 创建软链接启用配置
sudo ln -s /etc/nginx/sites-available/vite-project.conf /etc/nginx/sites-enabled/

# 校验配置是否有误
sudo nginx -t

# 重启nginx
sudo systemctl restart nginx

核心配置解析：页面静态请求由 Nginx 直接返回 dist 文件，无后端参与、极速响应；所有 /api/ 接口请求自动转发至后端 3001 端口，完美适配前后端分离生产架构。

九、全站 HTTPS 部署

采用 Let's Encrypt 免费可信证书，一键配置全站 HTTPS，自动跳转 HTTP 明文请求，提升网站安全性与搜索引擎收录权重。

9.1 安装证书工具

sudo apt install certbot python3-certbot-nginx -y

9.2 自动配置HTTPS

sudo certbot --nginx -d 你的域名

9.3 自动续期配置

# 测试续期
sudo certbot renew --dry-run

# 设置定时任务自动续期
crontab -e
# 添加内容
0 0 1 * * certbot renew && systemctl restart nginx

配置完成后，Certbot 会自动修改 Nginx 配置，实现永久 HTTPS 访问 + HTTP 强制跳转，配合定时任务自动续期，无需人工维护。

十、FRP 内网穿透配置（本地开发外网调试）

适用于本地开发外网调试、微信小程序/公众号接口调试、第三方服务回调测试等场景，无需上传服务器即可实现外网访问本地项目。

10.1 FRP 服务端配置（公网服务器）

公网服务器部署 FRP 服务端，开放穿透端口，作为内外网数据中转节点：

[common]
bind_port = 7000
token = 自定义密码

启动服务端：frps -c frps.ini

10.2 FRP 客户端配置（本地电脑）

本地电脑配置客户端，分别穿透前端页面、后端 API 接口，实现外网完整访问：

[common]
server_addr = 服务器IP
server_port = 7000
token = 自定义密码

# 前端页面穿透
[vite-web]
type = http
local_ip = 127.0.0.1
local_port = 5173
custom_domains = 穿透域名

# 后端接口穿透
[vite-api]
type = http
local_ip = 127.0.0.1
local_port = 3001
custom_domains = api.穿透域名

本地启动客户端：frpc -c frpc.ini，即可通过外网域名访问本地开发项目。

十一、项目生产更新流程（迭代上线规范）

标准化项目迭代更新流程，规避代码冲突、服务中断、部署报错等问题，适配生产稳定迭代：

11.1 前端更新流程

  1. 本地开发完成代码提交至 Git 仓库

  2. 服务器进入前端目录，执行 git pull 拉取最新代码

  3. 执行npm run build 重新生成 dist 目录

  4. 替换服务器 /var/www/vite-project/dist 文件

  5. 可选：清空浏览器缓存、Nginx 缓存

11.2 后端更新流程

  1. 服务器后端目录 git pull 拉取最新代码

  2. 依赖变更时执行npm install

  3. 执行 pm2 restart vite-node-api 重启服务

  4. 通过 pm2 logs 校验服务是否正常启动

生产最佳实践：先测试、后上线，后端采用「重启」而非「停止再启动」，最大限度缩短服务中断时间，保障业务连续性。

汇总线上部署、运行高频报错问题，配套精准排查思路与解决方案，快速定位修复故障：

12.1 页面访问空白/404

  • 故障原因：Vite 打包路径异常、Nginx 未配置前端路由 fallback 规则

  • 解决方案：检查 Nginxtry_files 配置，重新执行 npm run build 打包替换 dist 文件

12.2 /api/ 接口 404/500

  • 排查步骤：pm2 list 检查 3001 端口服务运行状态

  • 自测命令：curl http://127.0.0.1:3001/api/hello 本地接口连通性校验

  • 解决方案：核对 Nginx 代理地址、后端接口前缀是否统一，重启服务生效

12.3 HTTPS 证书失效

  • 解决方案：手动执行 certbot renew 续期，检查定时任务是否正常执行，重启 Nginx 生效

12.4 PM2 服务自动退出

  • 排查方式：pm2 logs 服务ID 查看详细报错日志，定位异常原因

  • 高频诱因：数据库连接失败、3001端口占用、.env 环境变量配置缺失

12.5 静态资源缓存不更新

  • 解决方案：前端打包开启资源哈希命名，清空 Nginx 缓存、浏览器强制刷新（Ctrl+F5）

十三、教程总结

本教程一站式覆盖 Vite前端打包、Node后端服务、MySQL数据库、Git版本管理、Linux服务器部署、PM2进程守护、Nginx反向代理、HTTPS加密、FRP内网穿透、项目迭代、线上排错 全链路生产流程。所有配置均经过生产验证、开箱即用，核心的「Nginx静态托管+API反向代理」架构，是目前前后端分离项目最稳定、最高效的生产部署方案。

十四、自用快捷运维指令手册（可直接复制）

本章为自用极速复制指令合集，汇总部署、运维、排错、迭代全部高频命令，无需翻阅全文，上线维护直接复制执行，提升操作效率。

14.1 本地项目进入目录（Windows）

# 本地项目根目录
cd C:\

14.2 服务器部署基础流程

# 进入服务器项目目录
cd /opt/.../example

# 安装后端依赖
npm install

# 构建前端生产dist文件
npm run build

# 初始化数据库表结构
node server/init-db.js

# PM2启动后端API服务
pm2 start server/index.js --name example

# 接口连通性验证
curl http://127.0.0.1:3001/api/health

14.3 PM2 服务快捷管理

# 查看所有运行服务
pm2 list

# 根据ID删除停止服务
pm2 delete 0

# 根据服务名重启服务
pm2 restart example

# 重启并刷新.env环境变量（更新配置必用）
pm2 restart example --update-env

# 查看服务实时日志
pm2 logs example

14.4 FRP 内网穿透启动命令（Windows）

# 本地启动frp客户端
.\frpc -c frpc.toml

14.5 端口监听 & 占用排查

# Linux 查看所有监听端口
ss -tulnp

# Linux 排查3001端口占用
lsof -i :3001

# Windows PowerShell 排查3001端口
Get-NetTCPConnection -LocalPort 3001

# Windows CMD 排查3001端口
netstat -ano | findstr :3001

14.6 Git 版本迭代快捷指令

# 推送main分支
git push origin main

# 首次推送绑定上游分支
git push -u origin main

# 绑定后直接推送
git push

# 安全强制推送（推荐，不覆盖他人代码）
git push --force-with-lease

# 拉取远程更新（仅下载不合并）
git fetch origin

# 拉取并自动合并
git pull origin main

# 拉取并变基（代码迭代推荐）
git pull --rebase origin main

高危禁止操作：严禁使用 git push -f 强制推送，会直接覆盖远程仓库他人提交代码，造成不可逆代码丢失！统一使用安全强制推送命令。

14.7 项目版本打包归档

# 打包当前最新代码为压缩包，用于版本备份
git archive -o example.zip HEAD