Quasar CLI Vite SSR模式下setup函数未处理错误求助

问题背景 #

• 为满足SEO需求，将Vue + Vite + Quasar的SPA项目重构为Quasar CLI Vite的SSR项目
• SPA开发模式quasar dev运行完全正常，但启动SSR开发模式quasar dev --mode ssr时出现错误；生产环境执行quasar build -m ssr --debug无错误，但npm run start启动服务时触发相同错误

错误信息 #

[Vue warn]: Unhandled error during execution of setup function 
  at <NavBar>
C:\Users\...MY PROJECT...\node_modules\ouch\handler\PrettyPageHandler.js:328
            SCRIPT_FILE: require.main.filename,
                                      ^

TypeError: Cannot read properties of undefined (reading 'filename')
    at PrettyPageHandler.__getServerAndRequestInfo (C:\Users\...\node_modules\ouch\handler\PrettyPageHandler.js:328:39)
at PrettyPageHandler.handle (C:\Users\...\node_modules\ouch\handler\PrettyPageHandler.js:143:41)
    at next (C:\Users\...\node_modules\ouch\Ouch.js:137:25)
    at C:\Users\...\node_modules\ouch\Ouch.js:141:9
    at Ouch.handleException (C:\Users\...\node_modules\ouch\Ouch.js:142:7)
    at Object.renderError [as error] (C:\Users\...\node_modules\@quasar\app-vite\lib\modes\ssr\ssr-devserver.js:44:16)
    at C:\Users\...\.quasar\ssr\compiled-dev-webserver.js:52:19

相关代码与依赖 #

NavBar组件（script setup部分） #

<script setup>
import { ref, watch, computed } from "vue";
import { useRoute, useRouter } from "vue-router";
import roomsData from "../data/roomsData.json";
import CustomDivider from "./CustomDivider.vue";
import LanguageSwitch from "./LanguageSwitch.vue";
import { debounce } from "quasar";

let route = useRoute();
let router = useRouter();
let routes = router.options.routes;

// 后续为基础代码，涉及Quasar、window、document
...
</script>

package.json依赖 #

"dependencies": {
    "@quasar/extras": "^1.0.0",
    "firebase": "^9.19.1",
    "pinia": "^2.0.11",
    "quasar": "^2.6.0",
    "vue": "^3.0.0",
    "vue-i18n": "^9.0.0",
    "vue-router": "^4.0.0",
    "@fullcalendar/core": "^6.0.2",
    "@fullcalendar/daygrid": "^6.0.2",
    "@fullcalendar/interaction": "^6.0.2",
    "@fullcalendar/vue3": "^6.0.2",
    "dotenv": "^16.0.3"
  },
  "devDependencies": {
    "@intlify/vite-plugin-vue-i18n": "^3.3.1",
    "@quasar/app-vite": "^1.0.0",
    "autoprefixer": "^10.4.2",
    "eslint": "^8.10.0",
    "eslint-config-prettier": "^8.1.0",
    "eslint-plugin-vue": "^9.0.0",
    "postcss": "^8.4.14",
    "prettier": "^2.5.1"
  },

排查困惑 #

• 不清楚PrettyPageHandler是什么，Quasar官方文档无相关说明
• 不理解require.main.filename的含义，项目使用Quasar Boot Files，没有传统的main.js入口文件
• NavBar组件未使用Firebase或FullCalendar，index.html已正确设置<!-- quasar:entry-point -->，完全找不到排查方向

解决建议 #

1. 修复NavBar组件的SSR兼容性问题 #

错误根源是NavBar组件的setup函数在服务端执行时调用了仅浏览器环境存在的API（如window/document），处理方式：

• 使用Quasar提供的process.client环境变量做判断，仅在客户端执行相关代码：

  if (process.client) {
    // 所有依赖window、document的逻辑放在这里
  }
  

• 或者使用Vue的onMounted钩子（仅在客户端触发）包裹浏览器相关逻辑：

  import { onMounted } from 'vue';
  onMounted(() => {
    // 此处执行需要浏览器环境的代码
  });
  

2. 解决PrettyPageHandler的异常 #

PrettyPageHandler是Quasar依赖的错误处理工具Ouch的组件，require.main.filename错误是前面的组件异常触发的工具本身的bug，解决组件问题后通常会自动消失；如果仍存在：

• 更新@quasar/app-vite到最新版本（当前使用1.0.0，存在已知SSR环境下的错误处理bug）
• 添加临时修复的boot文件：
  1. 在src/boot/ssr-fix.js中写入：

     if (process.server) {
       require.main.filename = process.argv[1];
     }
     

  2. 在quasar.config.js的boot数组中添加'ssr-fix'

3. 额外排查点 #

• 检查路由配置：确保所有路由组件都未在setup/created钩子中直接使用浏览器API
• 验证JSON文件导入：确认roomsData.json的导入在SSR环境下正常，必要时改用客户端动态导入
• 检查Pinia状态：如果使用Pinia，确保store的初始化逻辑不依赖浏览器环境

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