使用 GitHub Actions 将 VuePress 博客部署到 Firebase Hosting

太微2026-04-10运维VuePress Firebase GitHub Actions 静态站点

使用 GitHub Actions 将 VuePress 博客部署到 Firebase Hosting

本文以 VuePress 2 静态文档站点为例，说明如何把构建产物发布到 Firebase Hosting，并通过 GitHub Actions 在推送 main 时自动部署，以及在 Pull Request 上生成预览地址。文中参数与「本仓库」实际配置一致，便于你对照修改自己的项目 ID 与 Secret 名称。

1. 整体思路

环节	作用
本地 / CI 构建	`pnpm run docs:build` 生成静态文件目录（本仓库为 `docs/.vuepress/dist`）。
`firebase.json`	声明 Hosting 的 `public` 指向上述目录。
`.firebaserc`	绑定 Firebase 项目 ID（CLI 与部署目标）。
GitHub Secrets	存放服务账号 JSON（私钥），工作流通过 `${{ secrets.xxx }}` 引用，绝不写入仓库。
部署 Action	使用官方维护的 `FirebaseExtended/action-hosting-deploy` 上传产物。

flowchart LR
  subgraph repo[GitHub 仓库]
    A[推送 main 或 开 PR]
  end
  subgraph gha[GitHub Actions]
    B[checkout / pnpm / docs:build]
    C[action-hosting-deploy]
  end
  subgraph fb[Firebase]
    D[Hosting 站点]
  end
  A --> B --> C --> D

2. Firebase 控制台侧准备

在 Firebase Consoleopen in new window 创建或使用已有项目，记下 项目 ID（本示例为 blogs-c5156，请换成你自己的）。
在项目中启用 Hosting（按向导完成初始化即可）。
生成 服务账号密钥（用于 CI 非交互登录）：
- 「项目设置」→「服务帐号」→「生成新的私钥」，下载 JSON 文件。
- 该文件内容即后续要整份粘贴进 GitHub Secret 的凭证（不要提交到 Git）。

本地若使用 Firebase CLI，可用 firebase login 与 firebase deploy 做人工验证；CI 则完全依赖该 JSON。

3. 仓库内静态配置

3.1 `firebase.json`（指定发布目录）

本仓库将 VuePress 输出目录作为 Hosting 根目录：

{
  "hosting": {
    "public": "docs/.vuepress/dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
  }
}

public：必须与 vuepress build 产物路径一致，否则部署上去是空站或旧文件。
若你改过 docs 目录或 VuePress dest，这里要同步修改。

3.2 `.firebaserc`（默认项目）

{
  "projects": {
    "default": "blogs-c5156"
  }
}

部署时 Action 里仍会显式传 projectId，与这里保持一致即可。

4. GitHub Secrets：参数放哪里、工作流怎么取

4.1 需要配置的 Secret

在仓库 Settings → Secrets and variables → Actions 中新建 Secret：

Secret 名称（示例）	内容
`FIREBASE_SERVICE_ACCOUNT_BLOGS_C5156`	服务账号 JSON 的完整文件内容（一行或多行粘贴均可）

命名习惯上常使用 FIREBASE_SERVICE_ACCOUNT_<项目ID大写化>，与 Firebase 文档生成向导提示一致；名称必须与工作流里引用的一致。

4.2 在工作流中引用

GitHub Actions 使用表达式读取：

firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOGS_C5156 }}

secrets. 前缀 固定；后面是你在仓库里配置的 Secret 名字。
GITHUB_TOKEN 由 Actions 自动注入，用于 Action 与 GitHub API 交互（如评论里贴预览链接），不是 Firebase 凭证。

4.3 与 Firebase Action 输入项的对应关系

使用 FirebaseExtended/action-hosting-deploy 时，本仓库中相关参数如下。

Action 输入项	含义	本仓库取值示例
`repoToken`	GitHub API 令牌	`${{ secrets.GITHUB_TOKEN }}`
`firebaseServiceAccount`	服务账号 JSON	`${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOGS_C5156 }}`
`projectId`	Firebase 项目 ID	`blogs-c5156`
`channelId`	通道；`live` 表示正式站	合并到 `main` 时使用 `live`
（PR 预览）	不传 `channelId` 或按 Action 文档使用预览	PR 工作流生成临时预览 URL

若你更换了项目 ID，请同时修改 .firebaserc、工作流中的 projectId，并新建对应命名的 服务账号 Secret（或复用同一 JSON 但改名与文档一致）。

5. 与本仓库对应的三套工作流

5.1 CI：仅验证构建（不部署）

文件：.github/workflows/ci.yaml

触发：推送到 main、针对 main 的 PR。
作用：pnpm install + pnpm run docs:build，保证主分支与 PR 能通过构建。
不涉及 Firebase Secret，适合作为合并前的质量门。

5.2 合并到 main：部署正式环境

文件：.github/workflows/firebase-hosting-merge.yml

触发：push 到 main。
步骤摘要：Checkout → pnpm → Node 22 → docs:build → FirebaseExtended/action-hosting-deploy，并设置 channelId: live。
必备 Secret：FIREBASE_SERVICE_ACCOUNT_BLOGS_C5156。

与构建相关的环境变量示例：

env:
  NODE_OPTIONS: --max_old_space_size=8192

用于避免大型站点在 Node 中 OOM。

5.3 Pull Request：预览通道

文件：.github/workflows/firebase-hosting-pull-request.yml

触发：pull_request。
条件：github.event.pull_request.head.repo.full_name == github.repository（避免 fork PR 默认拿不到你仓库 Secret 的安全问题，可按团队策略调整）。
同样依赖 FIREBASE_SERVICE_ACCOUNT_BLOGS_C5156 与 projectId，由 Action 创建 预览 URL 并评论到 PR（需 repoToken 与相应 permissions）。

6. 排错清单

现象	可能原因
`Input required and not supplied: firebaseServiceAccount`	未在仓库 Secrets 中配置名称一致的服务账号，或 fork PR 无法读取 Secret。
部署成功但页面空白	`firebase.json` 的 `public` 与 VuePress 输出目录不一致。
构建 OOM	增大 `NODE_OPTIONS` 内存，或减少并行页面（视项目而定）。
仅本地能部署、CI 失败	CI 未使用 `pnpm install --frozen-lockfile` 或 Node 版本与本地差异过大。

7. 小结

静态路径由 firebase.json 锁定；项目由 .firebaserc 与 Action 的 projectId 锁定。
凭证只放在 GitHub Secrets，通过 ${{ secrets.名称 }} 注入，与 GITHUB_TOKEN 职责分离。
main 走 live 正式部署；PR 走预览工作流，形成「合并前可看效果」的协作方式。

按上述步骤替换为你自己的 Firebase 项目与服务账号 Secret 名后，即可在 2026 年及以后稳定使用同一套流程维护博客部署。

使用 GitHub Actions 将 VuePress 博客部署到 Firebase Hosting

ON THIS PAGE