Nginx部署vue项目无法直接访问其他路径的问题及解决_Vue.js

问题

nginx部署vue项目, 无法直接访问其他路径的解决方案

原因

nginx部署vue项目, 无法直接访问其他路径的原因是由于 vue项目是单页应用（spa），前端路由由javascript处理。

nginx默认配置无法直接访问其他路径，因为服务器会尝试查找对应路径的文件而不是返回index.html。需要在nginx配置中修改路由规则，将所有路径请求重定向到index.html。

补充

vue router采用了history模式，而nginx未正确配置重定向规则。

vue router默认使用hash模式（url带#），但若启用history模式，需服务器端支持将所有路径重定向到index.html，否则刷新或直接访问非根路径时会出现404。

解决方案

在nginx的配置文件添加下面转发配置

location / {
  try_files $uri $uri/ /index.html;
}

访问成功

工作原理分析

这段nginx配置代码主要用于处理前端单页应用（spa）的路由问题，核心原理如下：

路径匹配机制

location /表示匹配所有根路径下的请求。当用户访问任意url时（如/about或/contact），nginx会按照try_files指令的顺序尝试查找对应资源。

文件查找流程

try_files指令按从左到右的顺序尝试以下路径：

$uri：直接查找与请求uri完全匹配的静态文件（如/about.html）
$uri/：尝试将uri作为目录查找索引文件（如/about/index.html）
/index.html：当以上都失败时，最终返回前端入口文件

spa路由处理

对于单页应用：

直接访问静态资源（如css/js）时，前两个参数会匹配到实际文件
访问前端路由路径时，因物理文件不存在，最终会fallback到index.html
前端框架（如react/vue）接管路由，根据url渲染对应组件

典型应用场景

这种配置常见于：

前端框架生成的历史模式路由
需要支持直接url访问的spa应用
静态站点部署时保持路由完整性

配置示例扩展

实际部署时通常需要配合其他指令：

location / {
  try_files $uri $uri/ /index.html;
  expires -1; # 禁用缓存确保最新index.html
}

location /static/ {
  expires 1y; # 静态资源长期缓存
}

扩展知识点

如何配置nginx

安装nginx

在ubuntu系统中，可以使用以下命令安装nginx：

sudo apt update
sudo apt install nginx

安装完成后，启动nginx服务：

sudo systemctl start nginx

检查nginx状态

确保nginx运行正常：

sudo systemctl status nginx

如果服务未启动，可以使用以下命令启用开机自启动：

sudo systemctl enable nginx

配置nginx

nginx的主配置文件通常位于/etc/nginx/nginx.conf。建议在/etc/nginx/sites-available/目录中为每个站点创建单独的配置文件，并通过符号链接到/etc/nginx/sites-enabled/。

创建一个新的站点配置文件：

sudo nano /etc/nginx/sites-available/example.com

配置示例（替换example.com为实际域名或ip地址）：

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

启用配置文件：

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

测试配置

在重启nginx前，测试配置是否有语法错误：

sudo nginx -t

若无错误，重启nginx：

sudo systemctl restart nginx

设置防火墙

允许http和https流量：

sudo ufw allow 'nginx full'

配置ssl证书（可选）

使用certbot获取let’s encrypt免费ssl证书：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

证书会自动更新，手动测试更新：

sudo certbot renew --dry-run

静态文件服务

确保站点目录存在并设置权限：

sudo mkdir -p /var/www/example.com/html
sudo chown -r $user:$user /var/www/example.com/html

创建测试页面：

nano /var/www/example.com/html/index.html

内容示例：

<!doctype html>
<html>
<head>
    <title>welcome</title>
</head>
<body>
    <h1>success!</h1>
</body>
</html>

反向代理配置

将nginx配置为反向代理（例如指向本地node.js应用）：

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header host $host;
    proxy_set_header x-real-ip $remote_addr;
}

负载均衡配置

配置nginx作为负载均衡器：

安装nginx

在ubuntu系统中，可以使用以下命令安装nginx：

sudo apt update
sudo apt install nginx

安装完成后，启动nginx服务：

sudo systemctl start nginx

检查nginx状态

确保nginx运行正常：

sudo systemctl status nginx

如果服务未启动，可以使用以下命令启用开机自启动：

sudo systemctl enable nginx

配置nginx

创建一个新的站点配置文件：

sudo nano /etc/nginx/sites-available/example.com

配置示例（替换example.com为实际域名或ip地址）：

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

启用配置文件：

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

测试配置

在重启nginx前，测试配置是否有语法错误：

sudo nginx -t

若无错误，重启nginx：

sudo systemctl restart nginx

设置防火墙

允许http和https流量：

sudo ufw allow 'nginx full'

配置ssl证书（可选）

使用certbot获取let’s encrypt免费ssl证书：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

证书会自动更新，手动测试更新：

sudo certbot renew --dry-run

静态文件服务

确保站点目录存在并设置权限：

sudo mkdir -p /var/www/example.com/html
sudo chown -r $user:$user /var/www/example.com/html

创建测试页面：

nano /var/www/example.com/html/index.html

内容示例：

<!doctype html>
<html>
<head>
    <title>welcome</title>
</head>
<body>
    <h1>success!</h1>
</body>
</html>

反向代理配置

将nginx配置为反向代理（例如指向本地node.js应用）：

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header host $host;
    proxy_set_header x-real-ip $remote_addr;
}

该nginx配置片段用于将客户端请求反向代理到本地3000端口服务，同时设置必要的http头信息。

逐行解析

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header host $host;
    proxy_set_header x-real-ip $remote_addr;
}

核心指令说明

proxy_pass http://localhost:3000;

将所有匹配根路径（/）的请求转发到本地3000端口服务。适用于node.js、react开发服务器等场景。

proxy_set_header host $host;

保留原始请求的host头信息，避免后端服务因host改变出现路由问题。$host变量自动获取客户端请求的原始主机名。

proxy_set_header x-real-ip $remote_addr;

将客户端真实ip通过x-real-ip头传递给后端服务。$remote_addr变量包含客户端连接ip地址。

负载均衡配置

配置nginx作为负载均衡器：

upstream backend {
    server backend1.example.com;
    server backend2.example.com;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

nginx 配置常见字段及翻译

以下为 nginx 主要配置文件（nginx.conf）中常见字段的中英文对照及说明：

# 全局块配置（global block）
user www-data;                    # 运行 nginx 的用户和组
worker_processes auto;            # 工作进程数（auto 为自动分配）
pid /run/nginx.pid;               # pid 文件路径
error_log /var/log/nginx/error.log; # 错误日志路径

# events 块（连接配置）
events {
    worker_connections 1024;      # 单个工作进程的最大连接数
    use epoll;                    # 事件驱动模型（linux 推荐）
    multi_accept on;              # 允许同时接受多个连接
}

# http 块（核心配置）
http {
    include /etc/nginx/mime.types; # 包含 mime 类型定义文件
    default_type application/octet-stream; # 默认 mime 类型
    access_log /var/log/nginx/access.log; # 访问日志路径
    sendfile on;                  # 启用高效文件传输模式
    keepalive_timeout 65;         # 长连接超时时间（秒）
    gzip on;                      # 开启 gzip 压缩

    # server 块（虚拟主机配置）
    server {
        listen 80;                # 监听端口
        server_name example.com;  # 域名或主机名
        root /var/www/html;       # 网站根目录
        index index.html;         # 默认首页文件

        # location 块（路由配置）
        location / {
            try_files $uri $uri/ =404; # 文件存在性检查
        }

        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php7.4-fpm.sock; # php 处理
            include fastcgi_params;    # 包含 fastcgi 参数
        }

        # 错误页面配置
        error_page 404 /404.html;
        error_page 500 502 503 504 /50x.html;
    }
}

关键字段详解

全局块（global context）

worker_processes：定义 cpu 核心利用率，通常设为 auto。
error_log：错误日志级别可设置为 debug, info, warn, error, crit。

http 块（http context）

gzip_types：指定压缩的文件类型，例如 text/css application/json。
proxy_pass：反向代理时用于转发请求到后端服务（如 http://localhost:3000）。

server 块（server context）

listen：可扩展为 listen 443 ssl http2 启用 https。
server_name：支持通配符（*.example.com）和正则表达式。

location 块（location context）

匹配规则：

= 精确匹配
~ 正则匹配（区分大小写）
~* 正则匹配（不区分大小写）
^~ 前缀匹配

高级配置示例

# ssl 配置
server {
    listen 443 ssl;
    ssl_certificate /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;
    ssl_protocols tlsv1.2 tlsv1.3;
}

# 负载均衡
upstream backend {
    server backend1.example.com weight=5;
    server backend2.example.com;
    server backup.example.com backup;
}

server {
    location /api {
        proxy_pass http://backend;
    }
}

注意事项

修改配置后需测试语法：

nginx -t

重载配置：

nginx -s reload

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持代码网。


验证码：

Nginx部署vue项目无法直接访问其他路径的问题及解决

2025年12月25日 • Vue.js •我要评论

问题

原因

解决方案

工作原理分析

路径匹配机制

文件查找流程

spa路由处理

典型应用场景

配置示例扩展

扩展知识点

如何配置nginx

安装nginx

检查nginx状态

配置nginx

测试配置

设置防火墙

配置ssl证书（可选）

静态文件服务

反向代理配置

负载均衡配置

安装nginx

检查nginx状态

配置nginx

测试配置

设置防火墙

配置ssl证书（可选）

静态文件服务

反向代理配置

逐行解析

核心指令说明

负载均衡配置

nginx 配置常见字段及翻译

关键字段详解

高级配置示例

注意事项

总结

相关文章:

Webstorm怎么配置? Webstorm入门之软件配置教程

如何安装配置WebStorm? WebStorm安装与使用全方位指南

WebStorm常用插件以及实用设置分享

VSCode和webstorm怎么设置绿色护眼背景? 绿豆沙背景色的设置方法

发表评论