本指南展示如何构建一个 Flet 静态 Web 应用，并通过 GitHub Actions 把它部署到 GitHub Pages。

配置

1. 打开你的仓库根目录。
2. 如果不存在，创建此文件夹：.github/workflows/
3. 在该文件夹中创建一个工作流文件，例如：.github/workflows/build-deploy.yml —— 必须使用 .yml 或 .yaml 文件扩展名。
4. 把下方的 工作流配置 复制进该文件，并根据你的需要调整。
5. 提交并推送到 GitHub。
6. 打开 Actions 标签页来监控构建/部署进度。

::: dangerRepository settings 在 GitHub 中，打开 Settings → Pages，确保部署来源为 GitHub Actions。 :::

工作流

name: Web Build + Deploy to GitHub Pages [^1]

on: [^2]
  push: [^3]
  pull_request: [^4]
  workflow_dispatch: [^5]

concurrency: [^6]
  group: "pages" [^7]
  cancel-in-progress: false [^8]

env: [^9]
  UV_PYTHON: 3.12 [^10]

  # https://flet.dev/docs/reference/environment-variables
  FLET_CLI_NO_RICH_OUTPUT: 1 [^11]

jobs:
  build:
    name: Build web app
    runs-on: ubuntu-latest [^12]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 [^13]

      - name: Setup uv
        uses: astral-sh/setup-uv@v6 [^14]

      - name: Build app
        shell: bash
        run: | [^15]
          uv run flet build web --yes --verbose --base-url ${GITHUB_REPOSITORY#*/} --route-url-strategy hash

      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v4.0.0 [^16]
        with:
          path: build/web [^17]
          name: web-build-artifact [^18]
          retention-days: 20 [^19]

  deploy:
    name: Deploy to GitHub Pages
    if: github.event_name == 'push' && github.ref == 'refs/heads/main' [^20]
    needs: build [^21]
    runs-on: ubuntu-latest

    permissions: [^22]
      pages: write
      id-token: write

    environment: [^23]
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Setup Pages
        uses: actions/configure-pages@v5 [^24]

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4.0.5 [^25]
        with:
          artifact_name: web-build-artifact [^26]

1. Actions 列表中显示的工作流名称。
2. 工作流的触发块。
3. 每次推送都会构建。
4. pull request 更新时会构建。
5. 允许从 Actions 标签页手动运行。
6. GitHub Pages 部署的并发设置。
7. 把部署放入同一个 pages 并发组。
8. 保留当前正在运行的部署，而不是取消它。
9. 对所有 job 可用的环境变量。
10. uv 使用的 Python 版本。
11. 通过禁用富文本输出，产生更干净的 CI 日志。
12. 在 GitHub 托管的 Ubuntu 上运行构建 job。
13. 检出仓库代码。文档见此处。
14. 安装 uv。文档见此处。
15. 构建静态 Web 输出并设置：
    • --base-url ${GITHUB_REPOSITORY#*/}，使项目页面部署在 /<repo>/ 下。 如果你的仓库是 <username>.github.io，请使用 --base-url / 而不是仓库名。(docs)
    • --route-url-strategy hash，使路由在不依赖服务端重写的静态托管上也能工作。(docs)
16. 把静态文件作为 Pages 产物上传。文档见此处。
17. 使用 build/web 作为产物来源。
18. 随后由部署步骤使用的产物名称。
19. 保留产物 20 天。
20. 仅在推送到 main 时部署。PR 只构建不部署。按需调整。
21. 部署前等待构建 job 成功。
22. Pages 部署所需的权限。
23. 把部署输出 URL 连接到 GitHub 环境。
24. 配置 Pages 运行时。文档见此处。
25. 把产物部署到 GitHub Pages。文档见此处。
26. 必须与上传的产物名称一致。

可在此 处 查看实际效果。