如何在GitHub Pages部署Qwik框架？部署后页面异常求助

尝试将Qwik项目生成的静态文件输出到docs文件夹用于部署（GitHub Pages或自定义域名），但部署后网站JS文件无法正常工作，控制台报错：

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading '_qc_')
Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'Dt')

问题核心原因 #

• 部署域名与配置中的origin不匹配，导致资源路径解析错误
• Vite构建输出目录配置不完整，客户端与SSG生成的文件路径不一致
• 若使用GitHub Pages子路径部署，未配置正确的base路径

分步解决方案 #

1. 修正Vite配置文件（vite.config.ts）

统一构建输出目录为docs，并根据部署环境设置base路径：

import { qwikCity } from "@builder.io/qwik-city/vite";
import { qwikVite } from "@builder.io/qwik/optimizer";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig(() => {
  return {
    // 配置部署基础路径：GitHub Pages子仓库填 '/<RepoName>/', 根域名填 '/'
    base: '/<RepoName>/', 
    ssr: { target: "node", format: "cjs" },
    build: {
      // 统一设置输出目录为docs
      outDir: "docs",
    },
    plugins: [
      qwikCity(),
      qwikVite(),
      tsconfigPaths(),
    ],
  };
});

2. 修正SSG入口文件（entry.static.tsx）

更新origin为实际部署的域名，简化outDir路径写法：

import { qwikCityGenerate } from '@builder.io/qwik-city/static/node';
import { join } from 'path';
import render from './entry.ssr';

// 替换为你的实际部署域名
const DEPLOY_ORIGIN = 'https://<UserID>.github.io/<RepoName>'; 
// 或自定义域名：'https://your-custom-domain.com'

qwikCityGenerate(render, {
  origin: DEPLOY_ORIGIN,
  // 使用项目根目录下的docs文件夹，路径更可靠
  outDir: join(process.cwd(), 'docs'),
});

3. 验证构建与输出

执行构建命令后，确认docs文件夹下同时包含客户端静态资源和SSG生成的HTML文件：

npm run build.full

4. GitHub Pages部署额外设置

• 仓库设置中，将GitHub Pages的「Source」选择为docs文件夹
• 若使用自定义域名，需在docs文件夹中添加CNAME文件，内容为你的自定义域名

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