Valaxy Deploy to GitHub Pages

发表于

Valaxy Deploy to GitHub Pages

Valaxy 部署 GitHub Pages

📖 内容来源

✨ VALAXY
下一代静态博客框架
简洁、强大、高性能。遇见你一直想要的现代博客框架。

⚙️ 自带的 gh-pages.yml

.github/workflows/gh-pages.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      # The branch where the project source code resides
      # 项目源代码所在的分支
      - main
      - master
      - valaxy

jobs:
  build:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        node-version: [lts/*]
        os: [ubuntu-latest]
      fail-fast: false

    steps:
      - uses: actions/checkout@v2

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/

      - name: 📦 Install Dependencies
        run: npm i

      - name: 🌌 Build Valaxy Blog
        run: npm run build

      - name: 🪤 Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          force_orphan: true

在使用 pnpm create valaxy 创建模版项目时，已内置文件 .github/workflows/gh-pages.yml 以实现 GitHub Actions 的自动部署工作流。

选择 Github Repo，打开 Settings -> Action -> General -> Workflow permissions，选择 read and write permissions。
上传至 GitHub Repo，打开 Settings -> Pages，选择 gh-pages 分支。
gh-pages 已由 .github/workflows/gh-pages.yml 自动部署。

注意修改 gh-pages.yml 中的 on.push.branches 为你源代码所在的分支，默认为 main。

❌ Error: Action failed

Error: Action failed with "The process ‘/usr/bin/git’ failed with exit code 128"

Valaxy Error Action failed

不知道为什么在同一个仓库使用 github_token: ${{ secrets.GITHUB_TOKEN }} 还会权限不够。

✅ 解决方案

这个错误是因为 GitHub Actions 的默认 token 权限不足，无法推送到 gh-pages 分支。以下是几种解决方案：

1：使用个人访问令牌

  • 生成 Personal Access Token

    • 前往 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
    • 生成新 token，勾选 repo 权限
    • 复制生成的 token

  • 在仓库中设置 Secret

    • 前往仓库 Settings → Secrets and variables → Actions
    • 添加新的 secret，命名为 PERSONAL_TOKEN，值粘贴你的 token

  • 修改 workflow 文件

1
2
3
4
5
6
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    personal_token: ${{ secrets.PERSONAL_TOKEN }}
    publish_dir: ./dist
    # 其他配置...

2：使用 GitHub 自带的 GITHUB_TOKEN

修改 workflow 文件，添加写入权限：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: Deploy

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # ... 其他步骤
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

⚠️ 补充：关于 Node 警告的解决方案

在 workflow 中添加环境变量：

1
2
env:
  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true

或者在部署步骤中指定：

1
2
3
4
5
6
7
8
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    # 在 env 中设置
  env:
    ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true

如果以上方案都不行，请检查：

  1. 仓库是否属于组织？可能需要调整权限设置
  2. 是否启用了分支保护规则？需要临时禁用或配置允许强制推送

📝 修改后的 gh-pages.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
# valaxy 自带 gh-pages.yml
# valaxy.site/zh/guide/deploy

name: GitHub Pages

on:
  push:
    branches:
      # The branch where the project source code resides
      # 项目源代码所在的分支
      - main
      - master
      - valaxy

# 20260804
# 增加权限
permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        node-version: [lts/*]
        os: [ubuntu-latest]
      fail-fast: false

    steps:
      - uses: actions/checkout@v2

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/

      - name: 📦 Install Dependencies
        run: npm i

      - name: 🌌 Build Valaxy Blog
        run: npm run build

      - name: 🪤 Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          force_orphan: true

Valaxy build lts ubuntu-lastest