Ubuntu系统下部署Vue/Vite应用到Nginx完整步骤

更新时间：2026年02月27日 09:41:43 作者：衫水

这篇文章主要介绍了Ubuntu系统下部署Vue/Vite应用到Nginx的相关资料,包括配置加载优先级、部署前准备工作、Nginx配置方案、文件部署与权限设置、访问方式、故障排查、快速命令汇总和部署流程图,需要的朋友可以参考下

一、核心概念与文件结构

1. Nginx 配置加载优先级

主配置文件： /etc/nginx/nginx.conf

虚拟主机配置： /etc/nginx/sites-enabled/*（通过软链接加载 sites-available 里的文件）

关键原则：

sites-available 目录只是文件存放地，不会自动加载
sites-enabled 目录里的软链接才是真正被 Nginx 加载的配置
如果在 nginx.conf 主文件里已经定义了 server { listen 80; server_name IP; }，它会优先于 sites-enabled 里的配置匹配
修改配置后必须执行 sudo nginx -s reload 才能生效

二、部署前准备工作

1. 环境变量配置

编辑 .env.production 文件：

# 子应用模式（推荐，共用端口）
VITE_APP_BASE_API = '/flux/server'

# 独立域名模式（需要新域名）
# VITE_APP_BASE_API = '/server'

2. 构建项目

npm run build:prod   # 生成 dist/ 目录

三、Nginx 配置方案（二选一）

方案 A：在/etc/nginx/nginx.conf主文件中添加（推荐，更可靠）

适用场景： 当你执行 sudo nginx -t 看到 the configuration file /etc/nginx/nginx.conf 时

操作步骤：

备份主配置文件

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup

# ==========================================
# 全局配置段
# ==========================================
user www-data;                     # Nginx 工作进程运行用户
worker_processes auto;             # 自动根据 CPU 核数启动进程
pid /run/nginx.pid;                # 主进程 PID 文件
error_log /var/log/nginx/error.log; # 全局错误日志
include /etc/nginx/modules-enabled/*.conf; # 加载动态模块

events {
    worker_connections 768;        # 每个 worker 最大连接数
}

# ==========================================
# HTTP 配置段
# ==========================================
http {
    # 基础性能优化
    sendfile on;                   # 开启零拷贝文件传输
    tcp_nopush on;                 # 减少网络报文段数量
    types_hash_max_size 2048;      # MIME 类型哈希表大小
    
    # MIME 类型配置
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # SSL 协议配置（仅为预留，当前 server 块未启用 443）
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    # 日志配置
    access_log /var/log/nginx/access.log;

    # Gzip 压缩
    gzip on;

    # 引入其他配置文件（通常为空）
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;

    # ==========================================
    # 核心：主应用 + Flux 子应用虚拟主机
    # ==========================================
    server {
        listen 80;                           # 仅监听 IPv4 的 80 端口（HTTP）
        server_name 10.8.100.102;            # 精确匹配服务器 IP 地址

        # LASA_Data_Hub 主应用配置
        root /home/lasahub/LASA_Data_Hub_v1/frontend/dist;
        index index.html;

        location / {
            try_files $uri $uri/ /index.html; # 支持前端路由 history 模式
        }

        location /api/ {
            proxy_pass http://localhost:8899/api/; # 主应用后端代理
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }

        # Flux 子应用配置（关键部分）
        location /flux {
            alias /var/www/flux-frontend/dist;     # Flux 前端打包文件路径
            try_files $uri $uri/ /flux/index.html; # 必须包含子路径 /flux
        }

        location /flux/server {
            proxy_pass http://localhost:9099/api/; # Flux 后端 API 代理
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

编辑主文件

sudo nano /etc/nginx/nginx.conf

找到 server_name 你的IP; 所在的 server { listen 80; ... } 块，在其内部追加：

# ============= 新增 Flux 子应用配置 =============
location /flux {
    alias /var/www/flux-frontend/dist;          # 注意：用 alias，末尾不加 /
    try_files $uri $uri/ /flux/index.html;      # 注意：必须以 /flux 开头
}

location /flux/server {
    proxy_pass http://127.0.0.1:9099;           # 注意：末尾不加空格和 /
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# ============= 新增结束 =============

测试并 reload

sudo nginx -t              # 必须看到 "test is successful"
sudo nginx -s reload

方案 B：在sites-enabled/default中添加

适用场景： 主文件里没有 server_name IP; 这种具体 server 块时

操作步骤：

确认软链接存在

ls -l /etc/nginx/sites-enabled/
# 应该看到：default -> /etc/nginx/sites-available/default

如果没有，创建链接：

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

编辑 default 文件

sudo nano /etc/nginx/sites-available/default

在 server { listen 443 ssl ... } 块内追加相同的 location /flux {...} 配置
测试并 reload

sudo nginx -t
sudo nginx -s reload

四、文件部署与权限设置

1. 创建目录并复制文件

# 创建目标目录
sudo mkdir -p /var/www/flux-frontend/dist

# 复制打包后的文件（在项目根目录执行）
cp -r dist/* /var/www/flux-frontend/dist/

# 如果提示权限不足，在前面加 sudo
sudo cp -r dist/* /var/www/flux-frontend/dist/

2. 设置所有权和权限（必须执行）

# 把文件所有者改为 Nginx 进程用户（通常是 www-data）
sudo chown -R www-data:www-data /var/www/flux-frontend/dist

# 设置权限：所有者可读写执行，其他人只读执行
sudo chmod -R 755 /var/www/flux-frontend/dist

验证：

ls -ld /var/www/flux-frontend/dist
# 应显示：drwxr-xr-x www-data www-data /var/www/flux-frontend/dist

ls -l /var/www/flux-frontend/dist/index.html
# 应显示：-rw-r--r-- www-data www-data index.html

五、访问方式

子应用模式（本方案）

http://<服务器IP>/flux
https://<服务器IP>/flux  （如果主文件里有 HTTPS 配置）

注意：

浏览器会提示证书不安全（因为证书是域名的，不是 IP 的），点击“继续访问”即可测试
等域名 lasahub.inventec.com 批下来后，直接用域名访问，证书警告会消失

独立域名模式（需要额外配置 DNS）

https://flux.lasahub.inventec.com

六、故障排查速查表

问题 1：访问/flux报 404 Not Found

排查步骤：

检查文件是否存在

sudo ls -l /var/www/flux-frontend/dist/index.html

如果报错 No such file or directory → 文件没拷进去，重新执行 cp 命令

检查 Nginx 权限

sudo chown -R www-data:www-data /var/www/flux-frontend/dist
sudo nginx -s reload

看实时错误日志（最关键）

sudo tail -f /var/log/nginx/error.log

然后浏览器刷新 /flux，看日志里具体报什么路径找不到
如果显示 /var/www/flux-frontend/distflux/index.html → try_files 写错了，必须 /flux/index.html

检查 Nginx 配置是否已加载

sudo nginx -T | grep "/flux"
# 必须能看到 location /flux 和 location /flux/server 的内容

问题 2：修改配置后没生效

原因： 没 reload 或改错了文件

解决：

# 确认修改的是哪个文件
sudo nginx -t

# 必须 reload
sudo nginx -s reload

# 如果 reload 没效果，检查进程
ps aux | grep nginx
# 如果有多个 master 进程，说明有旧的 Nginx 没关闭，需要重启
sudo systemctl restart nginx

问题 3：权限不足无法编辑文件

正确做法：

# 不要改文件所有者！用 sudo 编辑
sudo nano /etc/nginx/nginx.conf

错误做法：

# 极其危险，不要这样做
chmod 777 /etc/nginx/nginx.conf
chown your-user /etc/nginx/...

七、快速命令汇总

# 1. 查看 Nginx 加载哪个配置文件
sudo nginx -t

# 2. 测试配置语法
sudo nginx -t

# 3. 重载配置（修改后必须执行）
sudo nginx -s reload

# 4. 重启 Nginx（当 reload 无效时）
sudo systemctl restart nginx

# 5. 查看错误日志
sudo tail -f /var/log/nginx/error.log

# 6. 查看访问日志
sudo tail -f /var/log/nginx/access.log

# 7. 检查端口监听
sudo netstat -tuln | grep nginx

# 8. 清理 dist 目录（重新部署前）
sudo rm -rf /var/www/flux-frontend/dist

八、部署流程图

九、关键注意事项总结

server_name 不重要时 ：用 _ 或 IP 都能匹配，关键是 listen 端口
alias vs root：alias 用于子路径，root 用于根域名
try_files 路径 ：必须以子路径开头，如 /flux/index.html
proxy_pass 格式：末尾不要加 / 和空格
权限：每次复制文件后都必须 chown 和 chmod
重载：每次修改 Nginx 配置后必须 sudo nginx -s reload
测试：sudo nginx -t 能发现 90% 的语法错误

最终验证命令（按顺序执行一次）：

sudo nginx -t
sudo nginx -s reload
ls -l /var/www/flux-frontend/dist/index.html
sudo chown -R www-data:www-data /var/www/flux-frontend/dist
# 浏览器访问：http://<你的IP>/flux

总结

到此这篇关于Ubuntu系统下部署Vue/Vite应用到Nginx的文章就介绍到这了,更多相关Vue/Vite部署到Nginx内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

Vue组件如何设置Props实例详解
props主要用于组件的传值,他的工作就是为了接收外面传过来的数据,与data、el、ref是一个级别的配置项,下面这篇文章主要给大家介绍了关于Vue组件如何设置Props的相关资料,需要的朋友可以参考下
2022-06-06
关于VUE的编译作用域及slot作用域插槽问题
这篇文章主要介绍了VUE 的编译作用域及slot作用域插槽问题，本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
2021-07-07
html中引入Vue.js的cdn实现简单的文档单页
这篇文章主要为大家介绍了html中引入Vue.js的cdn实现简单的文档单页示例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
2023-08-08
Vue中的默认插槽详解
在 Vue 中,插槽（Slot）是一种非常强大且灵活的机制,用于在组件中插入内容,默认插槽是在父组件中传递内容给子组件时使用的一种方式,这篇文章主要介绍了Vue中的默认插槽详解,需要的朋友可以参考下
2024-01-01
Vue之ref属性详解
这篇文章主要为大家介绍了Vue之ref属性，具有一定的参考价值，感兴趣的小伙伴们可以参考一下，希望能够给你带来帮助，希望能够给你带来帮助
2021-11-11
利用vue实现密码输入框/验证码输入框
这篇文章主要为大家详细介绍了如何利用vue实现密码输入框或验证码输入框的效果,文中的示例代码讲解详细,感兴趣的小伙伴可以参考一下
2023-08-08
vue 使用rules对表单字段进行校验的步骤
这篇文章主要介绍了vue 使用rules对表单字段进行校验的步骤，帮助大家更好的理解和使用vue，感兴趣的朋友可以了解下
2020-12-12
vue移动端微信授权登录插件封装的实例
今天小编就为大家分享一篇vue移动端微信授权登录插件封装的实例，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2018-08-08
Vue watch中监听值的变化,判断后修改值方式
这篇文章主要介绍了Vue watch中监听值的变化,判断后修改值方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-04-04
Vue privide 和inject 依赖注入的使用详解
这篇文章主要介绍了Vue privide 和inject 依赖注入的用法,本文通过示例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
2022-10-10