子目录部署Laravel+Vue+Sanctum SPA时API与路由路径错误问题

安全阿岳

2026-8-28

故障根因

三类问题叠加导致全流程失效：

前后端路由、请求基地址未配置子目录/子域名适配规则，默认指向站点根路径
Apache子域名虚拟主机配置未生效，请求实际落入主域Joomla应用的重写规则处理范围
主域Joomla多语言插件的重写规则优先级更高，拦截了未被正确路由的应用请求，强制追加语言前缀

第一步修正子域名虚拟主机配置（解决文档根不生效问题）

多数面板环境下手动修改配置不生效，是因为配置被面板默认规则覆盖，按以下要求配置：

子域名laravelapp.maindomain的DocumentRoot必须直接指向Laravel应用的public目录，而非laravelapp项目根目录，参考配置：

<VirtualHost *:80>
    ServerName laravelapp.maindomain.com
    DocumentRoot /var/www/maindomain/laravelapp/public
    <Directory /var/www/maindomain/laravelapp/public>
        AllowOverride All
        Require all granted
        Options Indexes FollowSymLinks
    </Directory>
</VirtualHost>

配置完成后必须重启Apache/httpd服务，仅重载配置在部分环境下不会读取新的虚拟主机规则。
配置有效性验证：在laravelapp/public目录下新建test.php写入<?php echo __DIR__;，访问laravelapp.maindomain.com/test.php，如果输出路径不是/xxx/maindomain/laravelapp/public，说明虚拟主机配置未被主配置文件加载，需检查Apache主配置中是否正确Include了对应虚拟主机配置文件，不要尝试在主域.htaccess中修改子域名规则，无任何效果。验证完成后删除test.php。

第二步修正Laravel端基础配置

解决API路径异常、Sanctum认证兼容问题：

# 走独立子域名部署时填写子域名地址，走主域子目录部署时填写子目录完整路径
APP_URL=https://maindomain.com/laravelapp
# 配置Session作用域，保证Sanctum认证Cookie可正常下发
SESSION_DOMAIN=.maindomain.com
SANCTUM_STATEFUL_DOMAINS=laravelapp.maindomain.com,maindomain.com

若暂未配置独立子域名、采用主域下/laravelapp子目录模式部署，需修改app/Providers/RouteServiceProvider.php，给路由统一追加前缀：

public function boot()
{
    $this->configureRateLimiting();
    $this->routes(function () {
        Route::prefix('laravelapp/api')
            ->middleware('api')
            ->namespace($this->namespace)
            ->group(base_path('routes/api.php'));

        Route::prefix('laravelapp')
            ->middleware('web')
            ->namespace($this->namespace)
            ->group(base_path('routes/web.php'));
    });
}

配置独立子域名部署时可跳过上述路由前缀配置

执行以下命令清空Laravel缓存：

php artisan config:clear
php artisan route:clear
php artisan cache:clear

第三步修正Vue端路由与请求配置

解决路由跳转丢前缀、API请求路径错误、静态资源加载异常问题：

配置vue-router基路径，打开路由初始化文件（通常为src/router/index.js）：

const router = createRouter({
    history: createWebHistory('/laravelapp/'), // 子目录部署时填写子目录前缀，末尾斜杠不可省略；独立子域名部署时填'/'
    routes: [/* 保留原有路由配置 */]
})

配置axios全局请求基路径，打开axios封装文件或入口文件main.js：

// 子目录部署配置
axios.defaults.baseURL = '/laravelapp/api/'
// 独立子域名部署配置
// axios.defaults.baseURL = '/api/'
axios.defaults.withCredentials = true
// 修正Sanctum CSRF Cookie请求路径
// 子目录部署用'/laravelapp/sanctum/csrf-cookie'，独立子域名部署用'/sanctum/csrf-cookie'

若使用Vite作为构建工具，修改vite.config.js配置base路径，避免打包后静态资源404：

export default defineConfig({
  base: '/laravelapp/', // 独立子域名部署时填'/'
  // 保留原有其他配置
})

重新执行前端打包命令，将生成的dist文件替换到部署对应目录：

npm run build

第四步配置Apache重写规则规避Joomla冲突

解决Joomla多语言规则拦截请求、前端路由刷新404问题：

在Laravel的public目录下的.htaccess文件顶部新增规则，优先处理应用自身请求：

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # 保留Laravel默认重写规则
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

若采用主域子目录模式部署，需在主域根目录的.htaccess文件*最顶部（所有Joomla规则之前）*新增排除规则，让/laravelapp路径下的请求不被Joomla处理：

RewriteEngine On
RewriteRule ^laravelapp/ - [L,NC]

规则配置完成后，清除浏览器缓存、Joomla应用缓存，避免旧重定向缓存影响结果。

验证流程

访问API路径确认可正常返回JSON结果，不出现Joomla页面、不自动追加/en/it等语言前缀
访问前端页面，确认路由跳转路径正确，刷新任意前端路由不返回404
测试登录流程，确认Sanctum认证Cookie正常下发，接口请求无401/419错误

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