SvelteKit部署Github Pages仅显示HTML内容问题排查

问题根源 #

1. 直接上传源码而非构建产物：你现在上传的是项目的src源码目录，而SvelteKit的app.html只是编译模板，不是最终可运行的静态文件——缺少编译后的JS逻辑、样式文件、路由映射，所以浏览器只能渲染纯HTML结构，没有交互和样式。
2. 重命名操作无意义且错误：手动把app.html改成index.html完全没必要，SvelteKit构建时会自动生成适配静态部署的index.html，手动修改源码文件反而会干扰正常构建流程。
3. 访问路径错误：正确的Github Pages访问路径不会包含/src/，因为部署的应该是构建后的产物，而非源码目录。

解决步骤 #

1. 配置SvelteKit为静态适配模式 #

• 安装静态适配器：

  npm install @sveltejs/adapter-static --save-dev
  

• 修改项目根目录的svelte.config.js，替换原有适配器配置：

  import adapter from '@sveltejs/adapter-static';
  import { vitePreprocess } from '@sveltejs/kit/vite';
  
  /** @type {import('@sveltejs/kit').Config} */
  const config = {
    preprocess: vitePreprocess(),
    kit: {
      adapter: adapter({
        pages: 'build',
        assets: 'build',
        fallback: null,
        precompress: false
      }),
      // 注意：如果是部署到个人主页（https://username.github.io），base设为空字符串；如果是项目仓库（https://username.github.io/仓库名），base设为'/仓库名/'
      paths: {
        base: ''
      }
    }
  };
  
  export default config;
  

2. 构建静态产物 #

运行构建命令，生成可部署的build文件夹：

npm run build

3. 部署到Github Pages #

推荐用Github Actions自动部署（无需手动上传文件）：

• 在项目根目录创建.github/workflows/deploy.yml文件，写入以下内容：

  name: Deploy to GitHub Pages
  on:
    push:
      branches: [main] # 替换成你的主分支名，比如master
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - name: Install dependencies
          run: npm install
        - name: Build project
          run: npm run build
        - name: Deploy to Pages
          uses: peaceiris/actions-gh-pages@v4
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./build
  

• 提交并推送这个文件到仓库主分支，然后前往Github仓库的「Settings」→「Pages」，设置「Source」为「Github Actions」，保存后每次推代码都会自动部署。

如果要手动部署：

• 创建gh-pages分支，把build文件夹里的所有内容（不是build文件夹本身）上传到这个分支，然后在Github Pages设置里选择gh-pages分支作为源。

4. 验证访问路径 #

部署完成后，正确访问路径应为：

• 个人主页仓库：https://username.github.io/
• 项目仓库：https://username.github.io/你的仓库名/

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