Nuxt3设置ssr:false纯客户端渲染静态部署后页面白屏无法加载

核心结论 #

Nuxt 3 完全支持无需服务器端运行Node进程的SPA应用托管，能力和Nuxt 2一致，你遇到的部署后白屏问题基本都是配置或部署操作不规范导致的。

操作误区说明 #

• 执行nuxi build默认输出的是面向Node服务端运行的构建产物，本身就依赖Node环境，纯客户端SPA场景不需要使用该命令构建
• 移除ssr: false配置后执行nuxi generate输出的是预渲染静态站点，这类场景如果没有做额外的客户端水合兼容配置，很容易出现静态内容可正常渲染、JavaScript交互逻辑完全失效的问题，不属于纯SPA模式的预期表现
• 本地执行npx serve .output/public运行正常、部署到线上白屏，核心原因是本地静态服务默认将资源根路径映射到当前public目录，而线上托管环境的资源路径映射和你的构建配置不匹配

正确配置与部署步骤 #

1. 配置文件调整
   在Nuxt配置文件中开启纯客户端渲染模式，如果站点不是部署在域名根路径（比如部署在https://your-domain.com/app/这类子路径下），必须同步配置基础路径，参考配置如下：

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
    ssr: false,
    app: {
        // 部署在域名根路径填'/', 部署在子路径就填对应子路径前缀，必须以斜杠结尾
        baseURL: '/'
    }
})

2. 构建操作
   直接执行nuxi generate命令，构建完成后纯静态产物会全部输出到.output/public目录下
3. 部署注意事项

• 将.output/public目录下的所有文件（包括_nuxt这类下划线开头的隐藏资源目录）全量上传到静态托管服务对应的站点根目录，不要随意修改产物内的目录结构
• 为静态托管服务配置SPA路由回退规则：将所有不存在的路径请求统一回退到index.html，否则直接访问子路由会触发404错误
• 不要直接通过本地文件协议（file://开头的路径）双击打开构建后的html文件，必须通过HTTP服务访问才能正常运行

白屏问题快速定位方法 #

部署后打开浏览器开发者工具的「网络」面板，检查资源加载状态：

• 如果静态资源（js、css文件）请求返回404，优先检查app.baseURL配置是否和线上实际访问路径一致，同时确认所有构建产物是否全量上传到了正确的目录
• 如果所有资源都加载成功但仍白屏，检查静态托管服务是否配置了错误的响应头，比如给js文件返回了错误的MIME类型

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