如何将SvelteKit部署到GitHub Pages？配置问题求助

刚踩过这个坑，给你分享下2024年能用的配置步骤，分两种项目类型说明：

一、Svelte + Vite 项目部署 #

快速自动部署方案（推荐） #

不用手动复制文件，用gh-pages包一键搞定：

• 安装依赖：npm install -D gh-pages
• 在项目根目录的package.json里添加部署脚本：

  "scripts": {
    // 保留原来的dev、build脚本，新增下面这行
    "deploy": "vite build && gh-pages -d dist"
  }
  

• 运行部署命令：npm run deploy
• 打开你的GitHub仓库，进入「Settings」→「Pages」，将「Source」设置为gh-pages分支的/root路径，保存后等待几分钟即可访问。

手动部署（不推荐） #

如果不想用工具，就手动处理：

• 本地运行npm run build，生成dist文件夹
• 把dist里的所有文件直接放到[username].github.io仓库的根目录（不要嵌套在子文件夹里！这是你之前404的核心原因）
• 提交推送后，在仓库Pages设置里选main分支的/root路径，等待部署完成。

二、SvelteKit 项目部署 #

SvelteKit不是纯静态项目，需要配置静态适配器才能部署到GitHub Pages：

1. 安装静态适配器 #

npm install -D @sveltejs/adapter-static

2. 修改svelte.config.js配置 #

替换原来的适配器为static，同时配置路径：

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, // 如果需要SPA fallback，设为`index.html`
      strict: true
    }),
    // 如果是部署到`[username].github.io`（个人主页），base留空；如果是项目仓库（比如`username/repo`），填`/repo`
    paths: {
      base: '',
    },
    // 强制预渲染所有页面为静态文件
    prerender: {
      entries: ['*']
    }
  }
};

export default config;

3. 启用全局预渲染 #

在项目的src/routes/+layout.js（或+layout.server.js，如果有服务端逻辑）中添加：

export const prerender = true;

4. 部署方式 #

方式一：用gh-pages包自动部署

• 安装gh-pages：npm install -D gh-pages
• 在package.json添加脚本：

  "scripts": {
    "deploy": "npm run build && gh-pages -d build"
  }
  

• 运行npm run deploy，然后在仓库Pages设置里选gh-pages分支的/root路径。

方式二：用GitHub Actions自动部署（更省心，代码推送自动部署）

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

name: Deploy to GitHub Pages

on:
  push:
    branches: [main] # 你的主分支名，比如main或master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 用你项目对应的Node版本
      - 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

提交这个文件后，每次推送到main分支，GitHub会自动帮你构建并部署。最后在仓库Pages设置里选gh-pages分支即可。

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