生产环境下如何启用Laravel Inertia Vue3 SSR？

我的Laravel + Inertia + Vue3 SSR应用运行正常，但SSR完全不生效——禁用浏览器JavaScript后页面空白。已部署在VPS，Nginx指向public目录，已构建SSR文件并通过Supervisor启动Inertia服务器。相关配置文件如下：

Supervisor配置

[program:inertia-ssr]
command=php /var/www/my-app/artisan inertia:start-ssr
autostart=true
autorestart=true
startretries=5
numprocs=1
startsecs=0
process_name=%(program_name)s_%(process_num)02d
stderr_logfile=/var/log/supervisor/%(program_name)s_stderr.log
stderr_logfile_maxbytes=10MB
stdout_logfile=/var/log/supervisor/%(program_name)s_stdout.log
stdout_logfile_maxbytes=10MB

app.js

import "./bootstrap";
import "../css/app.css";

import { createSSRApp, h } from "vue";
import { createInertiaApp } from "@inertiajs/vue3";
import { resolvePageComponent } from "laravel-vite-plugin/inertia-helpers";
import { ZiggyVue } from "../../vendor/tightenco/ziggy";

const appName = import.meta.env.VITE_APP_NAME || "Laravel";

createInertiaApp({
    title: (title) => `${title} - ${appName}`,
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.vue`,
            import.meta.glob("./Pages/**/*.vue")
        ),
    setup({ el, App, props, plugin }) {
        return createSSRApp({ render: () => h(App, props) })
            .use(plugin)
            .use(ZiggyVue)
            .mount(el);
    },
});

ssr.js

import { createSSRApp, h } from 'vue';
import { renderToString } from '@vue/server-renderer';
import { createInertiaApp } from '@inertiajs/vue3';
import createServer from '@inertiajs/vue3/server';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
import { ZiggyVue } from '../../vendor/tightenco/ziggy';

const appName = import.meta.env.VITE_APP_NAME || 'Laravel';

createServer((page) =>
    createInertiaApp({
        page,
        render: renderToString,
        title: (title) => `${title} - ${appName}`,
        resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
        setup({ App, props, plugin }) {
            return createSSRApp({ render: () => h(App, props) })
                .use(plugin)
                .use(ZiggyVue, {
                    ...page.props.ziggy,
                    location: new URL(page.props.ziggy.url),
                });
        },
    })
);

vite.config.js

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

Nginx配置

server {
    server_name my-app.com www.my-app.com;
    root /var/www/savage-portfolio/public;

    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
     }

    location ~ /\.ht {
        deny all;
    }


    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/my-app.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/my-app.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = my-app.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    server_name my-app.com www.my-app.com;
    return 404; # managed by Certbot
}

问题排查与修复方案 #

1. 补全Nginx SSR反向代理配置 #

当前Nginx未将SSR请求转发到Inertia SSR服务器，这是核心缺失项。Inertia SSR默认监听127.0.0.1:13714，修改Nginx的location /块：

location / {
    try_files $uri $uri/ @ssr;
}

location @ssr {
    proxy_pass http://127.0.0.1:13714;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

若自定义了SSR端口，替换13714为对应端口。

2. 验证SSR服务状态 #

• 查看Supervisor日志确认服务启动：

  cat /var/log/supervisor/inertia-ssr_stdout.log
  

  正常启动会输出Inertia SSR server started on http://127.0.0.1:13714类日志。
• 本地测试SSR接口：

  curl http://127.0.0.1:13714
  

  返回带<html>的渲染内容则服务正常，否则检查依赖或配置。

3. 启用Laravel SSR配置 #

确保config/inertia.php中开启SSR：

return [
    'ssr' => [
        'enabled' => true,
        'url' => 'http://127.0.0.1:13714',
    ],
];

无该文件则执行php artisan inertia:install生成后修改。

4. 检查依赖一致性 #

确认安装所有必需依赖，且@vue/server-renderer版本与Vue3完全匹配：

composer require inertiajs/inertia-laravel
npm install @inertiajs/vue3 @inertiajs/vue3/server @vue/server-renderer

5. 确认完整构建 #

部署时执行完整构建命令，确保生成SSR资源：

npm run build

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