整体流程 #
- 搭建开发所需环境
- 获取源代码并安装依赖包
- 在开发服务器上验证运行
- 创建生产环境构建
- 配置 Nginx 并发布构建好的文件
- 配置 HTTPS(如需)
- 设置重启时自动启动(如需)
以下步骤说明将提供具体的操作示例。
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 部署生产环境文件 #
- 创建发布文件夹 (例如:
/var/www/myapp)sudo mkdir -p /var/www/myapp - 复制构建好的文件(
dist中的内容)sudo cp -r /home/project/dist/* /var/www/myapp/ - 部署后,确认内容
ls -l /var/www/myapp # 有 index.html 和 assets 文件夹即可
STEP5.3 创建 Nginx 配置文件 #
Nginx 标准的配置管理方式是在 sites-available/ → sites-enabled/
中管理 server { ... } 配置块。
- 创建新的配置文件
sudo nano /etc/nginx/sites-available/myapp.conf - 填写以下内容 (针对 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
- 启用配置文件并禁用默认配置
# 通过符号链接将 myapp.conf 放入 sites-enabled sudo ln -s /etc/nginx/sites-available/myapp.conf /etc/nginx/sites-enabled/ # 如有默认站点则禁用 sudo rm /etc/nginx/sites-enabled/default - nginx 配置文件的语法检查 & 重新加载
sudo nginx -t sudo systemctl reload nginx - 在浏览器中访问
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. 故障排查 #
- 仍然显示”Welcome to nginx!”
- 未禁用默认配置
server_name不匹配
- 出现 404 错误
root设置的路径有误- SPA 未设置
try_files
- 浏览器无法访问
- 未开放端口 80/443（云服务的安全组或 UFW）
- 服务器 IP 或域名未正确分配
STEP9. 总结 #
- 开发：使用
npm run dev确认运行 - 构建：
npm run build→ 生成dist文件夹 - 使用 nginx 分发：将
dist中的内容放置到/var/www/myapp→ 设置myapp.conf→nginx -t→systemctl reload nginx - 支持 HTTPS：通过
certbot --nginx -d yourdomain.com等方式获取证书 - 自动启动：如果只有静态文件则使用 nginx，如果需要自建 API 则使用 PM2 或 systemd 管理 Node.js 常驻进程
