Vue.js应用带路径参数路由在Nginx中返回404问题排查

问题本质 #

Vue作为单页应用（SPA），所有路由逻辑都在浏览器端通过JS处理。当直接访问/ads、/ad/123这类子路由，或刷新页面时，Nginx/容器内的静态服务器会默认去服务器硬盘找对应路径的文件——但这些路径根本不存在（实际只有index.html和静态资源文件），因此返回404。

一、先搞定前端容器的静态服务配置 #

你提到单独运行前端容器时访问/ads也404，说明容器内的静态文件服务器未配置SPA fallback规则。如果用的是serve（常用静态文件服务器），启动命令必须加-s参数，让它把所有找不到的请求转发到index.html：

修改Docker启动命令 #

将前端容器的启动命令改为：

serve -s dist

如果用其他静态服务器（比如前端容器内置Nginx），也要添加类似的fallback规则。

二、调整Nginx配置 #

无论前端容器是否配置，Nginx作为反向代理或静态托管时，必须确保所有前端路由请求最终落到index.html上，以下分两种场景给出配置：

场景1：Nginx反向代理前端容器 #

server {
    listen 80;
    server_name your-domain;

    location / {
        proxy_pass http://frontend:8080; # 替换为Docker Compose中的前端服务名+内部端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # 关键：捕获前端容器返回的404，转发到index.html
        proxy_intercept_errors on;
        error_page 404 /index.html;
    }

    # 删除之前单独配置的/ads、/ad这类location，会干扰SPA路由逻辑
}

场景2：Nginx直接托管前端静态文件 #

如果Nginx直接挂载Vue打包后的dist目录，配置如下：

server {
    listen 80;
    server_name your-domain;
    root /path/to/dist;
    index index.html;

    location / {
        # 核心规则：先查找对应文件，找不到则返回index.html
        try_files $uri $uri/ /index.html;
    }
}

三、确认Vue路由配置 #

确保使用history模式（hash模式无此问题，但history模式URL更友好），示例代码：

import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  { path: '/', component: Home },
  { path: '/ads', component: AdList },
  { path: '/ad', component: AdCreate },
  { path: '/ad/:id', component: AdDetail },
  // 可选：添加全局404路由
  { path: '/:catchAll(.*)', component: NotFound }
]

const router = createRouter({
  history: createWebHistory(), // 必须使用createWebHistory，而非hash模式
  routes
})

export default router

四、Docker Compose检查点 #

• 确认前端容器的端口映射正确，内部端口与Nginx配置中proxy_pass的端口一致。
• Docker Compose中的服务名要与Nginx配置里的地址匹配（比如前端服务名为frontend，Nginx里就写http://frontend:8080）。

验证步骤 #

1. 单独启动前端容器，用serve -s dist启动，直接访问容器的/ads、/ad/123，确认能正常加载。
2. 启动Nginx容器，测试所有路由是否能正常访问、刷新不返回404。

内容的提问来源于stack exchange，提问作者Quentin M