
GitHub Pages 部署教程
文章摘要
AI
AI初始化中...
前往tianli博客
此内容根据文章内容生成,并经过人工审核,仅用于文章内容的解析与总结
GitHub Pages 部署教程
1、准备工作
- 拥有一个 GitHub 账号
- 项目代码已经放在 GitHub 仓库中
- 构建产物输出到一个目录(如 dist)
2、安装部署工具
以 Vite 项目为例。
2.1、使用 gh-pages 部署
推荐使用 gh-pages 工具自动部署:
npm install --save-dev gh-pages
配置:
以 Vite + Vue 项目为例,添加如下配置:
vite.config.ts
// vite.config.ts
export default defineConfig({
base: '/your-repo-name/', // 注意这里要加上你的 GitHub 仓库名
...
})
package.json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"deploy": "npm run build && gh-pages -d dist"
}
}
说明:
- base 是 GitHub Pages 的访问路径
gh-pages -d dist
表示把构建后的 dist 目录部署到gh-pages
分支
一键部署
npm run deploy
执行后会自动:
- 执行打包
- 将打包后的内容推送到 gh-pages 分支
- GitHub 会自动部署这个分支为静态页面
2.2、使用 GitHub Action 部署
配置
以 Vite + Vue 项目为例,添加如下配置:
vite.config.ts
// vite.config.ts
export default defineConfig({
base: '/your-repo-name/', // 注意这里要加上你的 GitHub 仓库名
...
})
创建 GitHub Action 配置
创建 .github/workflows/deploy.yml
文件
name: Deploy to GitHub Pages
on:
push:
tags:
- 'v*' # 当推送 v 开头的 tag 时触发
# 允许手动触发部署
workflow_dispatch:
# 设置 GITHUB_TOKEN 的权限
permissions:
contents: read
pages: write
id-token: write
# 允许一个并发部署
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Setup pnpm
uses: pnpm/action-setup@v2
with:
version: 10
run_install: false
- name: Get pnpm store directory
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v3
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Install dependencies
run: pnpm install
- name: Build project
run: pnpm build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: dist
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4
可以配置该 Action 执行的时机,这里配置的时机是:当推送 v 开头的 tag 时触发。
3、Github 配置
在你的仓库页面点击:
Settings → Pages
选择上一步配置的方式
配置完成之后就可以直接访问:
https://your-username.github.io/your-repo-name/
4、自定义域名(可选)
1、在仓库根目录创建一个名为 CNAME 的文件,内容为你的域名,例如:
www.example.com
2、更新Vite配置以适配自定义域名
// vite.config.ts
export default defineConfig({
base: '/', // 使用自定义域名时,base应该为根路径
...
})
3、域名DNS配置
在你的域名服务商处配置DNS记录:
# A记录指向GitHub Pages的IP
@ A 185.199.108.153
@ A 185.199.109.153
@ A 185.199.110.153
@ A 185.199.111.153
# 可选:配置www子域名
www CNAME guizimo.github.io
4、GitHub仓库设置
在你的仓库页面点击:
Settings → Pages
在 Custom domain 字段输入自定义域名,这里以 cova.guizimo.com 为例。
访问 https://cova.guizimo.com 预览效果
5、常见问题
5.1、无法自动开启 HTTPS
等待几小时,或检查 DNS 配置是否正确。
5.2、每次更新并部署后自定义域名失效
仓库根目录创建一个名为 CNAME 的文件,内容为你的域名。这一步是不能省略的。
5.3、刷新页面报错 404
使用 Hash 路由或配置 404.html fallback
本文是原创文章,采用 CC BY-NC-ND 4.0 协议,完整转载请注明来自 归墟
评论
匿名评论
隐私政策
你无需删除空行,直接评论以获取最佳展示效果