Firefly Docs

简体中文

English

简体中文

English

Appearance

部署指南 ​

本指南介绍如何将 Firefly 博客部署到各个平台。

本地构建 ​

如果你使用自己的网页服务器（如 Nginx、Apache 等），可以在本地构建后手动上传：

bash
pnpm build

构建产物位于 dist/ 目录，将该目录下的所有文件上传到你的服务器即可。

TIP

以下平台会自动构建和部署，无需手动构建。

Vercel ​

Vercel 是部署 Astro 项目最简单的平台之一。

方法一：通过 Vercel 控制台 ​

  1. 将你的项目推送到 GitHub / GitLab / Bitbucket
  2. 登录 Vercel，点击 Add New → Project
  3. 导入你的仓库
  4. Vercel 会自动检测 Astro 框架，配置如下：
    • Framework Preset: Astro
    • Build Command: pnpm build
    • Output Directory: dist
    • Install Command: pnpm install
  5. 设置 Node.js 版本：进入 Settings → General → Node.js Version，选择 22.x
  6. 点击 Deploy

方法二：使用 vercel.json ​

在项目根目录创建 vercel.json：

json
{
  "framework": "astro",
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "installCommand": "pnpm install"
}

TIP

Vercel 支持自动部署：每次推送到主分支时会自动触发构建和部署。

Netlify ​

Netlify 是另一个流行的静态站点托管平台。

方法一：通过 Netlify 控制台 ​

  1. 登录 Netlify
  2. 点击 Add new project → Import an existing project
  3. 连接 GitHub 仓库
  4. 配置构建设置：
    • Build command: pnpm build
    • Publish directory: dist
  5. 在 Environment variables 中设置 NODE_VERSION 为 22
  6. 点击 Deploy site

方法二：使用 netlify.toml ​

在项目根目录创建 netlify.toml：

toml
[build]
  command = "pnpm build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "22"

GitHub Pages ​

使用 GitHub Actions 可以将 Firefly 部署到 GitHub Pages。

步骤 ​

  1. 在 GitHub 仓库设置中：Settings → Pages → Source，选择 GitHub Actions

  2. 在项目根目录创建 .github/workflows/deploy.yml：

yaml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
  1. 在 astro.config.mjs 中设置 site 和 base：
js
export default defineConfig({
  site: "https://<username>.github.io",
  base: "/<repo-name>/",
});

WARNING

若使用自定义域名，或仓库名为 <username>.github.io，base 都无需设置。

Cloudflare Workers ​

Cloudflare Workers提供免费的 Serverless 边缘计算，其也能够托管静态站点。

方法一：通过 Cloudflare 仪表盘 ​

  1. 在项目根目录创建wrangler.toml：
toml
name = "firefly"
compatibility_date = "YYYY-MM-DD" # 更为今日

[assets]
directory = "./dist"

[vars]
NODE_VERSION = "22"
  1. 登录 Cloudflare Dashboard
  2. 进入 Compute → Workers & Pages → Create application → Connect Github
  3. 选择 GitHub 仓库
  4. 配置构建设置：
    • Build command: pnpm build
    • Deploy command: npx wrangler deploy
  5. 点击 Deploy

方法二：使用 Wrangler CLI ​

bash
# 安装 Wrangler
pnpm add -g wrangler

# 登录
wrangler login

# 构建并部署
pnpm build
wrangler deploy dist

Cloudflare Pages ​

Cloudflare Pages 提供免费的静态站点托管。

方法一：通过 Cloudflare 仪表盘 ​

  1. 登录 Cloudflare Dashboard
  2. 进入 Compute → Workers & Pages → Create application → Pages → Connect to Git
  3. 选择 GitHub 仓库
  4. 配置构建设置：
    • Framework preset: Astro
    • Build command: pnpm build
    • Build output directory: dist
  5. 在 Environment variables 中设置 NODE_VERSION 为 22
  6. 点击 Save and Deploy

方法二：使用 Wrangler CLI ​

bash
# 安装 Wrangler
pnpm add -g wrangler

# 登录
wrangler login

# 构建并部署
pnpm build
wrangler pages deploy dist

EdgeOne Pages ​

EdgeOne Pages 是腾讯云提供的边缘计算静态站点托管服务。

部署步骤 ​

  1. 登录 EdgeOne 控制台
  2. 进入 站点加速 → Pages，点击 新建项目
  3. 选择 从 Git 仓库导入，连接 GitHub / GitLab 仓库
  4. 配置构建设置：
    • 框架预设: Astro
    • 构建命令: pnpm build
    • 输出目录: dist
  5. 在环境变量中设置 NODE_VERSION 为 22
  6. 点击 开始部署

TIP

EdgeOne Pages 在中国大陆有边缘节点，对国内用户访问速度友好。

阿里云 ESA ​

阿里云 ESA（边缘安全加速） 提供了 Pages 静态站点托管功能。

部署步骤 ​

  1. 登录 阿里云 ESA 控制台
  2. 进入 Pages 功能，点击 创建项目
  3. 选择 从 Git 仓库导入，连接 GitHub / GitLab 仓库
  4. 配置构建设置：
    • 框架预设: Astro
    • 构建命令: pnpm build
    • 输出目录: dist
  5. 在环境变量中设置 NODE_VERSION 为 22
  6. 点击 开始部署

TIP

阿里云 ESA 在全球有大量边缘节点，尤其在中国大陆覆盖广泛，适合面向国内用户的博客。

自定义域名 ​

大多数平台都支持自定义域名绑定。一般步骤为：

  1. 在域名解析商处添加 CNAME 记录，指向平台分配的域名
  2. 在平台控制台中添加自定义域名
  3. 等待 DNS 生效（通常几分钟到几小时）
  4. 启用 HTTPS（大多数平台会自动申请 SSL 证书）

部署注意事项 ​

  • 确保 astro.config.mjs 中的 site 字段设置为你的实际域名
  • 如果使用子路径部署（如 https://example.com/blog/），需要设置 base 字段
  • 各平台的 Node.js 版本需要设置为 22 或更高
  • 首次部署后，后续推送代码会自动触发重新部署