How to quickly setup astro blog • The Life of Leung

前提条件

Astro 官网
AstroPaper 主题
本地环境使用 MacOS 系统
编辑器 - 推荐使用 VS Code
终端我使用 Tabby（个人习惯）

第一步：安装 Node.js

这里使用Node.js 版本管理工具 nvm，下面是安装脚本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

安装 Node.js TLS版本

nvm install 22
nvm use 22
nvm alias default 22
# 应该显示 v22.x.x
node -v
# 应该显示对应的版本号
npm -v

nvm 常用命令

# 查看云端有哪些可安装的版本 (macOS/Linux)
nvm ls-remote
# 查看你本地已经安装的所有版本
nvm ls
# 切换版本
nvm use

pnpm 安装

npm install -g pnpm

第二步：初始化 Astro 项目

默认主题

# 使用 pnpm 创建一个新项目
pnpm create astro@latest
# 进入项目目录安装依赖
pnpm install

使用 AstroPaper 主题

pnpm create astro@latest --template satnaing/astro-paper astro-paper
# 进入项目目录安装依赖
pnpm install

安装好后启动 Astro 开发服务器 / 构建

pnpm run dev
pnpm run build

预览

http://localhost:4321/

第三步：利用 GitHub 提供的免费托管服务

在 GitHub 创建一个项目，用于本地代码上传
在 GitHub 创建另一个项目，用于存放构建后的静态网站页面，项目名称： xxx.github.io
在 GitHub 项目xxx.github.io 创建部署密钥
在本地项目创建自动化部署文件，/.github/workflows/deploy.yml ,代码如下：

name: Deploy to GitHub Pages (using PNPM)

on:
  push:
    # ⚠️ 1. 【修改点】根据您的主分支名称修改 (main 或 master)
    branches:
      - main
  # 允许手动从 Actions 标签页运行工作流
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: ⬇️ Checkout Source Code (拉取源码)
        uses: actions/checkout@v4
        with:
          # 拉取完整的 Git 历史
          fetch-depth: 0

      - name: 🛠️ Setup pnpm (安装 pnpm)
        # 【解决找不到 pnpm 的问题】使用专用的 Action 确保 pnpm 可执行文件被找到
        uses: pnpm/action-setup@v3
        with:
          version: latest # 使用最新版 pnpm
          run_install: false # 暂不运行 pnpm install

      - name: ⚙️ Setup Node.js (配置 Node.js 环境及 PNPM 缓存)
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 建议使用 LTS 版本
          # 明确指定包管理器为 pnpm
          cache: 'pnpm'
          # 【解决缓存错误】明确指定 pnpm 的锁定文件路径
          cache-dependency-path: 'pnpm-lock.yaml'

      - name: 📦 Install Dependencies (安装依赖)
        # 使用 pnpm 命令安装依赖
        run: pnpm install --frozen-lockfile

      - name: 🔨 Build Project (执行构建)
        run: pnpm run build

      - name: 📋 Copy Deployment README (复制部署说明文件)
        # 将源码仓库根目录下的 README.md 复制到构建目录 dist 中
        run: cp README.md ./dist/README.md

      - name: 🚀 Deploy to xxx.github.io (部署到目标仓库)
        uses: peaceiris/actions-gh-pages@v3
        with:
          # 部署密钥 Secret 的名称
          deploy_key: ${{ secrets.LEMONTEABLOG_GITHUB_KEY }}
          # ⚠️ 2. 【修改点】目标仓库的名称，请替换 'your-github-username'
          external_repository: xxx/xxx.github.io
          # ⚠️ 3. 【修改点】要推送的目标分支 (通常是 main)
          publish_branch: main
          # 构建好的文件目录
          publish_dir: ./dist
          commit_message: ${{ github.event.head_commit.message }}