GitHub Pages

更新于 2026年11月1日

GitHub Pages 以两种 URL 形式之一提供静态文件目录：

用户/组织站点：https://<user>.github.io/，从名为 <user>.github.io 的仓库提供。没有子路径。
项目站点： https://<user>.github.io/<repo>/，从其他任意仓库提供。 /<repo>/ 前缀很重要；页面和资源的 URL 都必须包含它。

构建站点

htmlpress build

输出位于 .htmlpress/build/。

为项目站点配置 `base`

如果你发布在 https://<user>.github.io/<repo>/ 下，请设置 base，让构建中每个根相对 URL 都带上该前缀。编写链接时照常不带前缀（/guides/build/）；htmlpress 会自动加上。htmlpress start 和 preview 也在同一 base 下提供服务，因此开发环境与生产环境一致：

site: https://acme.github.io
base: /my-docs/

对于位于根路径的用户/组织站点，完全省略 base。

即使是项目站点，使用自定义域名时也不再有 /<repo>/ 子路径。如果你要绑定 docs.example.com 这样的域名，请不要设置 base，并把 site 设为最终域名。

手动部署

最简单的一次性部署方式是使用 gh-pages 包：

htmlpress build
npx gh-pages -d .htmlpress/build --nojekyll --dotfiles

这会把构建推送到 gh-pages 分支。在仓库设置中，把 Pages → Source 设为“Deploy from a branch”，并选择 gh-pages / / (root)。

务必保留 --nojekyll：分支部署会运行 Jekyll，它会丢弃以 _ 开头的文件夹，_htmlpress/ 中的主题也会随之丢失。--dotfiles 则会保留存放智能体技能的 .well-known/。

使用 GitHub Actions 部署

官方 Pages actions 是最简洁的方式：无需额外分支，也无需服务令牌。

name: deploy

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .htmlpress/build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

在仓库设置中把 Pages → Source 设为“GitHub Actions”。

自定义域名

在项目中、页面旁边添加一个写有你域名的 CNAME 文件：

docs.example.com

项目中所有非页面文件都会按原样、以相同路径复制到构建输出中，因此放在根 index.html 旁的 CNAME 会出现在部署的根目录。在域名注册商处配置 DNS（一条指向 <user>.github.io 的 CNAME 记录），并在 Pages → Custom domain 中设置该域名。

另请参阅

站点元数据：sitemap 和 Open Graph 标签中的绝对 URL 需要 site。
部署：返回托管平台索引。

用 ❤ 和 Htmlpress 构建