Fqzlr的博客

Cloudflare Workers 部署 Cloudflare‑ImgBed 图床完整教程

Thu, 07 May 2026 00:00:00 GMT

Cloudflare Workers 部署 Cloudflare‑ImgBed 图床完整教程#

本文基于官方文档)，从零教你用 Cloudflare Workers 部署专属图床，全程免费、无服务器、支持自动更新。

一、什么是图床？为什么选 Cloudflare‑ImgBed？#

1. 图床是什么#

图床 = 专门存放图片并生成可直接访问的 URL 的服务，用于博客、公众号、文档、笔记，Markdown 等场景，解决图片统一托管、跨平台复用、链接长期有效问题。

2. 为什么选本方案#

零成本：Cloudflare 免费额度足够个人日常使用
无服务器：不用买主机、不用配置环境
全球加速：Cloudflare CDN 全球节点，访问快
数据可控：自己部署、自己管理，不怕第三方图床跑路
多存储：支持 R2、Telegram、D1/KV 数据库
自动部署：GitHub Actions 一键部署 + 自动更新

3. Pages vs Workers（本教程选 Workers）#

可以做ip优选#

二、部署前期准备#

账号准备 - GitHub 账号（用于 Fork 项目、存 Secrets） - Cloudflare 账号（免费注册即可）
必备信息（后面会一步步拿） - Cloudflare Account ID - Cloudflare API Token（权限：编辑 Workers） - KV 或 D1 数据库 ID（二选一） - 可选：R2 存储桶名、Telegram 机器人信息
工具浏览器即可，无需本地环境、无需终端。

三、完整部署步骤（按顺序做）#

一步：Fork 开源项目

打开官方项目：CloudFlare ImgBed
点右上角 Fork → 选择你的 GitHub 账号 → 等待 Fork 完成。

第二步：准备 Cloudflare 资源#

2.1 获取 Account ID + API Token#

登录 Cloudflare Dashboard
右上角头像 → 我的个人资料 → API 令牌
创建令牌 → 选模板 编辑 Cloudflare Workers → 下一步 → 创建令牌
复制并保存生成的 API Token（只出现一次）
返回 Dashboard 首页，右侧找到并复制 Account ID。

2.2 创建数据库（KV 或 D1 二选一）#

方案 A：KV 数据库（读写更快）#

存储和数据库 → Workers KV → 创建实例
名称填 img_url → 创建
复制 命名空间 ID

方案 B：D1 数据库（免费额度更高）#

存储和数据库 → D1 SQL 数据库 → 创建数据库
名称填 img_d1 → 创建
复制 数据库 ID
进入「控制台」执行项目提供的 init.sql 初始化语句

2.3（可选）创建 R2 存储桶#

存储和数据库 → R2 对象存储 → 创建存储桶
自定义名称，复制保存 存储桶名称

第三步：配置 GitHub Secrets（关键）#

进入你 Fork 的仓库
Settings → Secrets and variables → Actions → New repository secret
按表添加，必填项必须填，二选一填一个即可

Secret 名称	说明	是否必填
CLOUDFLARE_API_TOKEN	Cloudflare API 令牌	✅ 必填
CLOUDFLARE_ACCOUNT_ID	Cloudflare 账户 ID	✅ 必填
KV_NAMESPACE_ID	KV 命名空间 ID	KV/D1 二选一
D1_DATABASE_ID	D1 数据库 ID	KV/D1 二选一
R2_BUCKET_NAME	R2 存储桶名	可选
WORKER_NAME	Worker 名称（默认 cloudflare-imgbed）	可选
WORKER_VARS	业务变量（JSON 格式，如 TG 配置）	可选

安全提醒：一律用 Secrets，不要用 Variables（公开可见）。

第四步：运行部署（手动 / 自动二选一）#

方式 1：手动触发部署#

进入仓库 Actions 页面
左侧选择 Deploy to Cloudflare Workers
点 Run workflow
分支选 main → 直接 Run workflow
等待执行成功（约 1–3 分钟）

方式 2：开启自动部署（推荐）#

Actions 页面找到 Upstream Sync
点 Enable workflow
以后上游更新 → 自动同步 main → 自动部署，全程不用管

四、部署成功 ; 访问使用#

访问地址：“
部署后必须配置存储渠道（R2/Telegram 等）才能上传图片，在后台管理面板配置即可。

五、后续更新维护#

1. 自动更新（推荐）#

保持 Upstream Sync 开启，上游更新自动同步并部署。

2. 手动更新#

仓库点 Sync fork 同步上游
触发自动部署；或手动再跑一次 Deploy workflow。

六、常见问题#

部署失败：检查 Secrets 是否填错、权限是否正确
无法上传：未配置存储渠道，去后台绑定 R2 或 Telegram
链接打不开：确认 Worker 已启用、名称与子域名拼写正确

七、总结#

用 Cloudflare Workers 部署图床，全程免费、无服务器、10 分钟搞定，适合个人长期稳定使用。按本文步骤：Fork → 拿 Cloudflare 信息 → 配 GitHub Secrets → 一键部署，即可拥有专属高速图床。

Cloudflare IP优选

Sun, 03 May 2026 00:00:00 GMT

一、Cloudflare IP优选#

步骤1：添加路由规则#

登录Cloudflare账号，进入你绑定的Astro博客域名控制台（左侧导航栏选择对应域名）。
找到左侧导航栏的路由（Rules），点击进入后选择「转换规则」或「路由」（按当前Cloudflare界面显示为准）。
点击「添加路由」，进入路由配置页面。
路由地址填写：你的Astro域名/*（示例：blog.xxx.com/*），含义是匹配Astro博客的所有页面（包括文章、静态资源），统一走优选节点。
无需额外添加规则，直接保存并确认路由配置。

步骤2：配置DNS解析（关键步骤）#

在Cloudflare域名控制台，找到左侧导航栏的DNS → 记录，点击进入。
点击「添加记录」，开始配置优选解析。
记录类型：选择「A记录」或「CNAME」均可。
名称：可自定义前缀（如cdn、speed、ip），用于标识优选节点（示例：speed.xxx.com）。
目标：填写UP主提供的Cloudflare优选节点/地址（格式：任意文字或字母.cf.090227.xyz，直接复制粘贴，确保地址正确）。
代理状态：必须关闭云朵图标（即关闭Cloudflare代理），否则优选无效。
点击「保存」，完成优选解析记录添加。

步骤3：绑定Astro主域名到优选节点#

再次点击「添加记录」，配置Astro主域名的解析。
记录类型：与上一步一致（A记录/CNAME）。
名称：填写Astro主域名前缀（如blog，即blog.xxx.com，若为根域名则填写@）。
目标：填写上一步创建的优选记录名称（示例：speed.xxx.com），将主域名指向优选节点。
代理状态：保持关闭（与上一步一致）。
点击「保存」，等待1-3分钟解析生效，刷新Astro博客即可感受到访问速度提升。

原理：Astro博客主域名 → Cloudflare优选地址 → Cloudflare最优节点，自动选择国内延迟最低的IP，减少静态资源（Astro生成的HTML、CSS、图片）加载耗时。

二、Astro博客Markdown文章编写与发布#

Astro博客的文章均以Markdown格式编写，核心需遵循Astro的Frontmatter元数据规范，以下步骤完全适配Astro框架，新手可直接复刻。

1. 文章存放位置（Astro固定路径）#

所有Markdown文章，需放在Astro项目源码的 src/content/posts/ 文件夹下（若没有posts文件夹，可手动创建，Astro默认读取该路径下的文章）。
文章格式：必须是纯Markdown文件（后缀为.md），文件名建议用英文/拼音（如astro-blog-guide.md），避免中文乱码。
图片、附件等资源：统一放在 src/content/posts/images/ 或 src/assets/ 文件夹下（推荐前者，方便管理），引用时使用相对路径。

2. 文章必备元数据（Astro Frontmatter规范）#

每篇Markdown文章顶部，必须编写固定格式的Frontmatter元数据（用---包裹），适配Astro的文章渲染逻辑，示例如下（可直接复制修改）：

1
---
2
title: 文章标题（如：Astro博客部署全流程指南）
3
date: 2026-05-03 19:00:00
4
description: 文章简短描述（100字内，用于SEO和文章列表展示）
5
cover: /src/content/posts/images/cover.jpg
6
tags: [Astro, 静态博客, 部署]
7
categories: 技术教程
8
draft: false
9
author: 作者名
10
pubDate: 2026-05-03 19:00:00
11
---

元数据字段说明

title：文章标题，必填，将作为博客文章的标题展示。
date：文章发布时间，格式为YYYY-MM-DD HH:MM，适配Astro时间渲染。
description：文章简短描述，控制在100字内，用于SEO优化和博客文章列表展示。
cover：文章封面图路径，可填写本地相对路径（需对应资源存放位置）或网络图片链接。
tags：文章标签，用英文逗号分隔并包裹在中括号内，适配Astro标签功能，方便分类检索。
categories：文章分类，可自定义，用于博客文章分类展示。
draft：草稿状态，true为草稿（不显示在博客），false为正式发布（必填）。
author：作者名，可选，适配Astro作者展示功能。
pubDate：可选，与date一致即可，部分Astro主题需配置以正常显示发布时间。

Astro支持的Markdown功能（适配文章编写） Astro完全支持标准Markdown语法，可正常使用标题（# ~ ######）、段落、列表（有序/无序）、代码块（```包裹）、链接、图片、引用（>）等功能，同时支持GFM扩展语法（如表格、任务列表），可满足日常文章编写需求，无需额外配置。
推荐编辑器（适配Astro，二选一）
VS Code（推荐，适配Astro开发）：原生支持Astro项目结构，可安装Markdown预览插件，实现语法高亮、实时预览，同时可编辑Astro项目代码，适合兼顾开发与写作的用户。
Obsidian（OC，适合纯写作）：可视化编辑，实时预览Markdown效果，无需记忆语法，适合不想接触代码的新手；可将Obsidian的文章文件夹，与Astro项目的src/content/posts/文件夹关联，编写完成后直接同步，无需手动复制。

Firefly 博客搭建教程

Wed, 29 Apr 2026 00:00:00 GMT

Firefly 博客部署教程#

根据Firefly 官方文档，涵盖全流程操作，代码可直接复制，小白可按步完成，附关键避坑提示。说明：基于 Windows 系统；命令可直接执行。

第一篇：前置准备｜安装必备环境#

一、前言#

Firefly 是 Astro 静态博客主题，本文是作者的搭建笔记，为以后回溯搭建过程，为后续操作筑牢基础。

二、必备软件清单#

Node.js：核心环境，版本 ≥22
pnpm
Git：用于拉取源码、提交代码
VS Code：推荐编辑器，用于修改配置、写文章

三、分步安装教程#

1. 安装 Node.js#

访问 https://nodejs.org/，下载 LTS 版。
image.png|528

image.png|534

终端执行 node -v、npm -v，输出版本号即成功。

image.png

注意：安装后重启终端，无效则重启电脑。

2. 安装 pnpm#

终端执行：npm install -g pnpm
执行 pnpm -v 输出版本号即成功，权限不足用管理员终端。

image.png

注意：网络超时切换手机热点。

3. 安装 Git#

1.访问 https://git-scm.com/download/win，下载最新版并默认安装。

image.png

2. 一直下一步就行了，全程默认安装。

4. 安装 VS Code（可选）#

1.访问 https://code.visualstudio.com/，下载并安装，勾选“创建桌面快捷方式”和“将 Code 加入 PATH”。

image.png

推荐安装中文插件。

image.png

四、常见环境问题排查#

node 命令无效 → 重新安装并勾选“Add to PATH”，重启终端/电脑。
pnpm 权限不足 → 用管理员终端执行命令。
git 无反应 → 重启电脑，无效则重装。

第二篇：源码托管｜Fork Firefly 官方仓库#

一、前言#

通过Fork官方仓库，获得自己的独立仓库，可自由修改内容、同步官方更新，后续推送代码到该仓库，Cloudflare会自动触发构建部署。

二、前置准备#

已完成第一篇环境安装（Node ≥22、pnpm、Git、VS Code）
已注册并登录 GitHub 账号

三、Fork 操作步骤（1分钟完成）#

打开Firefly官方仓库：https://github.com/CuteLeaf/Firefly
点击页面右上角的「Fork」按钮（绿色/灰色，位置显眼）。
等待3-5秒，页面自动跳转，此时你已拥有「自己的Firefly仓库」（仓库地址：https://github.com/你的GitHub用户名/Firefly）。

关键说明：Fork后的仓库归你所有，修改内容不会影响官方仓库，后续可一键同步官方更新，适合长期维护。

第三篇：本地搭建｜克隆仓库 + 本地预览调试#

一、前言#

将你Fork后的仓库克隆到本地，安装依赖后启动本地服务，用于预览修改效果（仅本地查看，无需打包，推送代码后Cloudflare自动部署）。

二、前置准备#

已完成前两篇操作（环境安装、Fork仓库）
新建空文件夹：路径无中文、无空格、无特殊字符（示例：D:\blog）

三、分步操作教程#

四、克隆你自己的仓库到本地#

进入 你的 Fork 仓库 页面
点击 Code → 复制 HTTPS 地址
执行克隆（把地址换成你自己的）：运行

1
git clone https://github.com/你的用户名/Firefly.git

1
cd Firefly

2. 安装本地依赖（仅用于本地预览）#

安装依赖（用 pnpm）运行

1
pnpm install

3. 启动本地预览服务#

1
pnpm dev

等待10-30秒，终端显示访问地址： http://localhost:4321
打开浏览器输入该地址，看到Firefly默认首页，即本地搭建成功。

4. 本地简单调试#

修改配置 / 文章 → 保存自动刷新

在项目根目录创建wrangler.toml： Cloudflare Workers部署需要

1
name = "firefly"
2
compatibility_date = "YYYY-MM-DD" # 更为今日
3

4
[assets]
5
directory = "./dist"
6

7
[vars]
8
NODE_VERSION = "22"

2.简单修改站点信息。

停止服务：Ctrl + C
重新启动：pnpm dev
本地仅用于预览，无需执行任何打包命令（Cloudflare会自动打包）。

5. 本地开发完成后#

1.先配置本地 Git 身份

打开电脑的终端（Mac/Linux） 或 Git Bash/CMD（Windows），执行 2 条命令：

1
# 1. 设置你的GitHub用户名（就是你GitHub主页的用户名）
2
git config --global user.name "你的GitHub用户名"
3

4
# 2. 设置你的GitHub绑定邮箱（就是你注册GitHub用的邮箱）
5
git config --global user.email "你的GitHub邮箱"

检测是否成功

1
git config --global user.name
2
git config --global user.email

1
能显示出你填的信息，就说明绑定好了。

2. 推送到 GitHub：

1
git add .
2
git commit -m "更新内容"
3
git push

第四篇：部署配置｜Cloudflare 关联GitHub自动构建#

一、前言#

这是核心部署步骤，关联你的GitHub仓库后，后续只要推送代码到GitHub，Cloudflare会自动执行「安装依赖→打包→上线」，全程无需手动操作。

二、前置准备#

已完成前几篇操作（环境安装、Fork仓库、本地搭建，简单修改，上传到github）
已注册并登录Cloudflare账号（无账号可注册：https://dash.cloudflare.com/）
你的GitHub仓库已包含完整Firefly源码

三、分步配置教程#

1. 新建 Cloudflare Worker 应用#

登录 Cloudflare 控制台 打开浏览器访问官方控制台：https://dash.cloudflare.com/，输入账号密码完成登录。
进入 Workers & Pages 页面 登录后，在左侧菜单栏找到并点击 Workers 和 Pages（英文对应：Workers & Pages），进入应用管理页面。
创建应用程序 在页面右上角，点击 创建应用程序（英文对应：Create application），进入应用创建流程。
关联 GitHub 代码仓库 在创建页面中，选择 连接到 Git（Connect Git），然后选中 GitHub，按照页面提示完成授权，允许 Cloudflare 访问你的 GitHub 账号。
选择目标仓库 授权完成后，系统会列出你的 GitHub 所有仓库，从中选中需要部署到 Cloudflare Worker 的代码仓库（如 Firefly 仓库）。
配置构建设置 ：

Build command: pnpm build
Deploy command: npx wrangler deploy

发起首次部署 配置完成后，点击页面底部的 部署（Deploy），启动首次自动部署流程。
等待自动构建完成 Cloudflare 会自动执行三个操作：拉取 GitHub 仓库代码 → 执行构建命令 → 将项目部署至 Workers 服务器，耐心等待即可。。

2. 验证自动部署是否成功#

当构建状态显示“成功”后，点击 Worker 项目顶部的 临时域名（格式为：xxx.workers.dev）。
打开浏览器访问该临时域名，若页面展示效果与本地预览的博客首页完全一致，说明 Cloudflare Worker 与 GitHub 自动部署配置成功。

第五篇：绑定域名（Spaceship 平台域名适配）#

完成 Cloudflare Worker 自动部署后，默认使用 xxx.workers.dev 临时域名访问，为了提升专业性和记忆性，我们将你在 Spaceship 平台注册的域名，绑定到 Worker 应用，全程适配博客框架，步骤清晰无冗余。

一、绑定前准备（必做）#

确认域名状态：登录 Spaceship 控制台，确认你的域名状态为“正常”，未被锁定、未过期，且已完成实名认证（若有要求），避免因域名异常导致绑定失败。

二、Step 1：在 Cloudflare 中添加自定义域名#

登录 Cloudflare 控制台，进入之前创建的 Worker 项目主页（可通过左侧「Workers 和 Pages」找到对应项目）。
在项目主页左侧导航栏，点击 触发器（英文：Triggers）选项卡，找到「自定义域」模块，点击 添加自定义域。
在弹出的输入框中，填写你在 Spaceship 平台的域名（如 yourdomain.com 或 www.yourdomain.com），点击添加。
添加后，Cloudflare 会自动生成对应的 DNS 解析记录（CNAME 记录），记录下该 CNAME 记录的「目标值」（通常为你的 Worker 临时域名），后续需在 Spaceship 平台配置该解析。

三、Step 2：在 Spaceship 平台配置 DNS 解析（核心步骤）#

这一步是关键，需在你的域名所在平台（Spaceship）修改 DNS 解析，将域名指向 Cloudflare Worker，具体操作如下：

登录 Spaceship 控制台：打开浏览器，访问 https://www.spaceship.com/zh/auth/?returnUrl=%2Flaunchpad%2F，输入你的账号密码完成登录（若已登录可直接进入）。
进入域名管理页面：登录后，点击顶部「Launchpad」（控制台），找到「Domain Manager」（域名管理）模块，在域名列表中找到你要绑定的域名，点击该域名进入详情页。
进入 DNS 解析设置：在域名详情页中，找到「DNS」选项（或「DNS 解析」「解析设置」），点击进入 DNS 解析配置页面，删除当前无关的解析记录（避免冲突）。
添加 CNAME 解析记录：点击「添加记录」（或「新增解析」），按以下参数填写（适配 Cloudflare Worker 绑定）：
1. 记录类型：选择 CNAME（核心类型，用于将域名指向 Worker 临时域名，适配 IP 动态变化场景）；
2. 主机记录：填写 @（代表主域名，如 yourdomain.com）或 www（代表带 www 前缀的域名，如 www.yourdomain.com，建议两者都添加）；
3. 记录值：粘贴 Step 1 中 Cloudflare 生成的 CNAME 目标值（即 Worker 临时域名，如xxx.workers.dev），确保填写无误；
4. TTL（缓存时间）：设置为 10~60 分钟（数值越小，解析生效越快，新手可直接默认）；
点击「保存」，完成 DNS 解析配置，此时 Spaceship 平台的域名解析已指向 Cloudflare Worker。

四、Step 4：验证域名绑定是否成功#

DNS 解析生效时间通常为 10 分钟~24 小时（新域名生效较快，老域名可能需等待更久），可通过以下两种方式验证绑定结果：

浏览器直接访问：打开浏览器，输入你绑定的域名（如 yourdomain.com），若能正常显示博客首页，且地址栏有 HTTPS 小锁标志，说明绑定成功；若提示“无法访问”，请耐心等待解析生效，或检查解析记录填写是否正确。
在线工具查询：使用 DNS 解析查询工具（如 DNSChecker.org），输入你的域名，查询 CNAME 记录，若查询结果与你配置的 Worker 临时域名一致，说明解析已生效，绑定成功。

###五、域名绑定常见问题排查

解析配置后无法访问：检查 Spaceship 平台的 CNAME 记录值是否与 Cloudflare 生成的目标值一致，TTL 设置是否过小，若无误，耐心等待解析生效（最长 24 小时）；同时确认 Cloudflare 中自定义域已添加成功。
浏览器提示“不安全”：检查 Cloudflare 的 SSL/TLS 加密模式是否设置正确，证书是否已生效，若未生效，等待几分钟后刷新页面重试。
提示“域名已被占用”：确认该域名未被其他 Cloudflare 项目绑定，若已绑定，先删除原有绑定，再重新添加。
DNS 解析修改无效：检查 Spaceship 平台的域名 DNS 服务器是否为默认服务器，若已修改为第三方 DNS，需先改回默认或同步解析记录至对应 DNS 服务器。

Git 使用教程

Tue, 28 Apr 2026 00:00:00 GMT

Git 详细使用教程（命令行版，附命令作用解释）#

Git 是目前最流行的分布式版本控制系统，核心作用是跟踪文件变化、管理代码版本，支持多人协作开发，可随时回滚到历史版本，避免代码丢失或冲突。本教程全程使用命令行操作（Windows 用 Git Bash、Mac/Linux 用终端），从基础配置到高级用法，逐一讲解命令作用和实操场景，新手可直接跟着步骤练习。

一、Git 前期准备（必做）#

1. 安装 Git#

先在本地安装 Git，安装完成后，打开命令行，输入以下命令验证是否安装成功：

Terminal window

1
git --version

命令作用：查看当前 Git 版本，若输出类似git version 2\.43\.0，说明安装成功；若提示“命令不存在”，需重新安装 Git。

2. 初始配置（绑定身份，关键步骤）#

Git 每次提交代码时，会记录提交者的身份（用户名和邮箱），用于区分不同开发者，必须配置后才能正常提交代码。

Terminal window

1
# 配置用户名（建议和 GitHub/GitLab 用户名一致）
2

3
git config --global user.name "你的用户名"
4

5

6

7
# 配置邮箱（建议和 GitHub/GitLab 绑定邮箱一致）
8

9
git config --global user.email "你的邮箱地址"

命令作用详解：

git config：Git 的配置命令，用于设置 Git 相关参数；
\-\-global：全局参数，意味着该配置在当前电脑所有 Git 项目中生效（若只想针对单个项目配置，去掉该参数，进入项目后再执行）；
user\.name/user\.email：配置提交者的用户名和邮箱，后续所有提交记录都会显示该信息。

验证配置是否成功：

Terminal window

1
git config --list

命令作用：查看当前 Git 的所有配置，若能看到刚才设置的用户名和邮箱，即为配置成功。

二、Git 核心概念（先理解，再操作）#

在使用命令前，先明确 3 个核心工作区域，避免操作混乱：

工作区（Working Directory）：就是你本地电脑上的项目文件夹，你直接修改的文件都在这个区域；
暂存区（Stage/Index）：临时存放你修改的文件，相当于“缓存区”，用于确认哪些修改需要提交到版本库；
版本库（Repository）：Git 真正保存版本的地方，存放所有提交记录，可随时回滚到任意历史版本（分为本地版本库和远程版本库，如 GitHub）。

核心流程：工作区修改 → 提交到暂存区 → 提交到本地版本库 → 推送到远程版本库（如 GitHub）。

三、本地仓库操作（最基础，必练）#

本地仓库是 Git 操作的基础，无需联网，可独立完成版本管理，适合个人开发或离线工作。

1. 初始化本地仓库（创建新项目）#

适用于：新建一个项目，想要用 Git 管理版本（比如本地新建的文件夹，需要变成 Git 仓库）。

Terminal window

1
# 1. 进入你要管理的项目文件夹（先切换到目标路径）
2

3
cd 你的项目文件夹路径（如：cd /Users/xxx/Documents/MyProject）
4

5

6

7
# 2. 初始化 Git 仓库
8

9
git init

命令作用详解：

cd：切换目录命令，用于进入你要操作的项目文件夹（若路径错误，会提示“没有该文件或目录”）；
git init：初始化 Git 仓库，执行后会在项目文件夹中生成一个隐藏的 \.git 文件夹（该文件夹是 Git 版本库的核心，不要删除），此时项目就被 Git 管理起来了。

注意：每个项目只需初始化一次，初始化后，该文件夹就是 Git 仓库了。

2. 查看工作区状态（高频命令）#

无论做什么操作，建议先查看工作区状态，确认当前文件的修改情况，避免误操作。

Terminal window

1
git status

命令作用：查看工作区、暂存区的文件状态，常见输出场景：

未修改：提示 nothing to commit, working tree clean（工作区干净，没有任何修改）；
已修改但未提交到暂存区：文件名称显示为 modified（红色）；
已提交到暂存区但未提交到版本库：文件名称显示为 staged（绿色）。

3. 将修改的文件提交到暂存区#

适用于：你在工作区修改了文件（如新增、修改、删除文件），需要先提交到暂存区，再准备提交到版本库。

Terminal window展开收起

1
# 方式1：提交所有修改的文件（最常用）
2

3
git add .
4

5

6

7
# 方式2：提交指定文件（适用于只提交部分修改）
8

9
git add 文件名（如：git add index.html）
10

11

12

13
# 方式3：提交指定文件夹下的所有文件
14

15
git add 文件夹名（如：git add src/）

展开收起

命令作用详解：

git add：将工作区的修改“暂存”起来，告诉 Git“这些修改我要提交到版本库，请先记录下来”；
\.：表示当前目录下所有修改的文件（包括新增、修改、删除），简化操作，无需逐个指定文件；
提交后，再执行git status，会看到文件变成绿色，提示“changes to be committed”（暂存区有等待提交的内容）。

4. 将暂存区的文件提交到本地版本库#

这是 Git 版本管理的核心步骤，提交后，修改会被永久保存到本地版本库，生成一条新的版本记录。

Terminal window

1
git commit -m "提交说明"

命令作用详解：

git commit：将暂存区的内容提交到本地版本库，完成一次版本更新；
\-m \&\#34;提交说明\&\#34;：必填参数，用于描述本次提交的内容（如“新增登录页面”“修复首页轮播bug”），建议说明清晰，方便后续查看历史记录时，快速知道该版本做了什么修改；
提交成功后，会提示类似 1 file changed, 2 insertions$\+$ 的信息，表示“1个文件被修改，新增了2行内容”。

注意：必须先执行 git add，再执行 git commit，否则会提示“没有可提交的内容”。

5. 查看提交历史记录#

适用于：查看之前的提交记录，包括提交者、提交时间、提交说明、版本号（用于回滚版本）。

Terminal window展开收起

1
# 方式1：查看完整历史记录（详细）
2

3
git log
4

5

6

7
# 方式2：查看简洁历史记录（只显示版本号和提交说明，推荐）
8

9
git log --oneline
10

11

12

13
# 方式3：查看所有提交记录（包括回滚的记录）
14

15
git reflog

展开收起

命令作用详解：

git log：显示所有提交记录，每条记录包含版本号（40位哈希值）、提交者、提交时间、提交说明；
\-\-oneline：简化输出，每条记录只显示前7位版本号和提交说明，更易查看；
git reflog：比 git log 更全面，会记录所有操作（包括回滚、撤销提交），常用于找回误删的版本。

6. 版本回滚（恢复到历史版本）#

适用于：修改出错、代码丢失，需要恢复到之前的某个稳定版本（核心操作，务必掌握）。

Terminal window展开收起

1
# 第一步：查看历史版本，获取要回滚的版本号（前7位即可）
2

3
git log --oneline
4

5

6

7
# 第二步：回滚到指定版本（两种常用方式）
8

9
# 方式1：彻底回滚，删除回滚版本之后的所有提交记录（谨慎使用，适合个人开发）
10

11
git reset --hard 版本号（如：git reset --hard a1b2c3d）
12

13

14

15
# 方式2：安全回滚，保留回滚版本之后的修改（推荐，适合多人协作）
16

17
git revert 版本号（如：git revert a1b2c3d）

展开收起

命令作用详解：

git reset \-\-hard 版本号：强制回滚到指定版本，工作区、暂存区的内容都会同步到该版本，之后的提交记录会被删除（无法恢复，谨慎使用）；
git revert 版本号：不会删除任何提交记录，而是生成一条新的提交记录，将代码恢复到指定版本，后续的修改仍然保留（安全，多人协作时优先使用）；
版本号：通过 git log \-\-oneline 获取，如 a1b2c3d（前7位即可，Git 会自动识别）。

7. 撤销工作区的修改（未提交到暂存区）#

适用于：在工作区修改了文件，但还没执行 git add，想放弃修改，恢复到上一次提交后的状态。

Terminal window

1
# 撤销单个文件的修改
2

3
git checkout -- 文件名（如：git checkout -- index.html）
4

5

6

7
# 撤销所有工作区的修改（未 add 的）
8

9
git checkout .

命令作用：放弃工作区的所有未暂存修改，将文件恢复到最近一次 git commit 或 git add 后的状态（注意：撤销后，修改会彻底丢失，无法恢复）。

8. 撤销暂存区的修改（已 add 但未 commit）#

适用于：执行了 git add，将修改提交到了暂存区，但还没执行 git commit，想撤销暂存，重新修改。

Terminal window

1
git reset HEAD 文件名（如：git reset HEAD index.html）
2

3

4

5
# 撤销所有暂存区的修改
6

7
git reset HEAD .

命令作用：将暂存区的修改撤销回工作区，此时文件状态会从“绿色（staged）”变回“红色（modified）”，之后可以重新修改、重新 add。

四、远程仓库操作（多人协作必备）#

远程仓库（如 GitHub、GitLab、Gitee）是用于多人共享代码的服务器，本地仓库的代码可以推送到远程，也可以从远程拉取别人的代码，实现协作开发。

前提：你已经有一个远程仓库（如在 GitHub 上创建了仓库），且本地 Git 已配置好远程仓库地址。

1. 关联远程仓库（第一次绑定）#

适用于：本地已有 Git 仓库，想要和远程仓库绑定，实现代码同步。

Terminal window

1
git remote add origin 远程仓库地址

命令作用详解：

git remote：用于管理远程仓库的命令（如添加、删除、查看远程仓库）；
add：添加远程仓库；
origin：远程仓库的别名（默认用 origin，可自定义，如 git remote add github 远程地址），后续操作远程仓库时，用别名即可，无需输入完整地址；
远程仓库地址：从 GitHub/GitLab 复制，一般分为 HTTPS 和 SSH 两种（HTTPS 无需配置密钥，直接输入账号密码即可；SSH 需要配置密钥，无需每次输入账号密码，推荐长期使用）。

查看已关联的远程仓库：

Terminal window

1
git remote -v

命令作用：查看当前本地仓库关联的所有远程仓库，输出会显示远程仓库的别名、地址，以及可进行的操作（fetch：拉取，push：推送）。

2. 从远程仓库拉取代码（同步别人的修改）#

适用于：多人协作时，别人将代码推送到了远程仓库，你需要将远程的最新代码拉取到本地，保持本地和远程同步。

Terminal window

1
# 方式1：拉取远程默认分支（如 main/master）的最新代码（最常用）
2

3
git pull origin main（或 master，取决于远程仓库的默认分支名）
4

5

6

7
# 方式2：拉取远程指定分支的代码
8

9
git pull origin 分支名（如：git pull origin develop）

命令作用详解：

git pull：等价于 git fetch \+ git merge，即先从远程拉取最新代码到本地临时区域，再自动合并到当前本地分支；
origin：远程仓库别名；
main/master：远程仓库的默认分支（GitHub 现在默认分支是 main，旧版本是 master）；
注意：拉取代码前，建议先执行 git commit，将本地的修改提交到本地版本库，避免拉取时出现代码冲突。

3. 将本地代码推送到远程仓库（分享自己的修改）#

适用于：你在本地完成了代码修改（已 commit 到本地版本库），想要将修改推送到远程仓库，让别人看到你的代码。

Terminal window展开收起

1
# 方式1：推送本地默认分支到远程默认分支（第一次推送需加 -u）
2

3
# 第一次推送（绑定本地分支和远程分支，后续可直接用 git push）
4

5
git push -u origin main（或 master）
6

7

8

9
# 后续推送（已绑定分支，无需加 -u）
10

11
git push origin main（或 master）
12

13

14

15
# 方式2：推送本地指定分支到远程指定分支
16

17
git push origin 本地分支名:远程分支名（如：git push origin develop:develop）

展开收起

命令作用详解：

git push：将本地版本库的提交记录推送到远程仓库；
\-u：第一次推送时使用，用于绑定本地分支和远程分支（如本地 main 分支绑定远程 main 分支），后续推送时，直接输入 git push 即可，无需指定别名和分支；
推送失败常见原因：① 本地代码不是最新的（需先 git pull 拉取远程最新代码，解决冲突后再推送）；② 没有远程仓库的权限（检查账号密码或 SSH 密钥配置）。

4. 克隆远程仓库到本地（第一次下载）#

适用于：本地没有该项目，直接从远程仓库下载完整的项目代码（包括所有版本记录）。

Terminal window

1
git clone 远程仓库地址

命令作用详解：

git clone：将远程仓库的所有内容（包括代码、版本记录、分支）完整下载到本地，自动创建项目文件夹，并初始化 Git 仓库；
执行后，本地会自动关联该远程仓库（别名默认是 origin），无需再执行 git remote add；
示例：git clone https://github\.com/用户名/项目名\.git（HTTPS 地址），或 git clone git@github\.com:用户名/项目名\.git（SSH 地址）。

5. 查看远程分支#

Terminal window展开收起

1
# 查看本地所有分支
2

3
git branch
4

5

6

7
# 查看远程所有分支
8

9
git branch -r
10

11

12

13
# 查看本地和远程所有分支
14

15
git branch -a

展开收起

命令作用：

git branch：查看本地已有的分支，当前所在分支会用 \* 标记；
\-r：查看远程仓库的所有分支；
\-a：查看本地和远程的所有分支（远程分支会显示为 remotes/origin/分支名）。

6. 切换/创建分支（多人协作核心）#

多人协作时，建议每人在自己的分支上开发，避免直接修改默认分支（main/master），开发完成后再合并到默认分支。

Terminal window展开收起

1
# 1. 创建新分支（并切换到该分支，最常用）
2

3
git checkout -b 分支名（如：git checkout -b develop）
4

5

6

7
# 等价于以下两条命令：
8

9
# git branch 分支名（创建分支）
10

11
# git checkout 分支名（切换到该分支）
12

13

14

15
# 2. 切换到已有的本地分支
16

17
git checkout 分支名（如：git checkout main）
18

19

20

21
# 3. 切换到远程分支（并创建本地对应分支）
22

23
git checkout -b 本地分支名 origin/远程分支名（如：git checkout -b develop origin/develop）

展开收起

命令作用详解：

git checkout \-b 分支名：一次性完成“创建分支+切换分支”，高效便捷；
分支命名建议：按功能命名（如 feature/login，表示登录功能分支）、按bug修复命名（如 fix/banner\-bug），便于区分。

7. 合并分支（将开发分支的代码合并到默认分支）#

适用于：在开发分支（如 develop）完成开发后，将代码合并到默认分支（如 main），让修改生效。

Terminal window

1
# 1. 先切换到要合并到的目标分支（如 main 分支）
2

3
git checkout main
4

5

6

7
# 2. 合并开发分支（如 develop 分支）到当前分支（main）
8

9
git merge develop

命令作用：将指定分支（如 develop）的所有修改，合并到当前所在的分支（如 main），合并后，main 分支就包含了 develop 分支的所有代码。

注意：合并时可能会出现代码冲突（如两个人同时修改了同一个文件的同一行），此时需要手动解决冲突：

执行 git merge 后，Git 会提示“冲突文件”；
打开冲突文件，找到标记冲突的地方（用 \<\<\<\<\<\<\<、=======、\>\>\>\>\>\>\> 标记）；
修改冲突内容（保留需要的代码，删除冲突标记）；
执行 git add \. 和 git commit \-m \&\#34;解决合并冲突\&\#34;，完成合并。

8. 删除分支（分支开发完成后）#

Terminal window展开收起

1
# 删除本地分支（分支已合并到主分支，可安全删除）
2

3
git branch -d 分支名（如：git branch -d develop）
4

5

6

7
# 强制删除本地分支（分支未合并，强行删除，谨慎使用）
8

9
git branch -D 分支名
10

11

12

13
# 删除远程分支
14

15
git push origin --delete 分支名（如：git push origin --delete develop）

展开收起

命令作用：删除无用的分支，保持分支结构清晰，避免混乱。

五、常用补充命令（高频实用）#

Terminal window展开收起

1
# 1. 查看当前分支的提交差异（对比工作区和暂存区）
2

3
git diff
4

5

6

7
# 2. 查看暂存区和本地版本库的差异
8

9
git diff --cached
10

11

12

13
# 3. 查看两个分支之间的差异
14

15
git diff 分支1 分支2（如：git diff main develop）
16

17

18

19
# 4. 暂存当前修改，切换到其他分支（临时切换分支，不提交当前修改）
20

21
git stash  # 暂存当前修改
22

23
git stash pop  # 恢复暂存的修改（恢复后，暂存记录删除）
24

25
git stash list  # 查看所有暂存记录
26

27

28

29
# 5. 重命名本地分支
30

31
git branch -m 旧分支名 新分支名
32

33

34

35
# 6. 更新远程分支列表（远程删除了分支，本地同步）
36

37
git fetch --prune

展开收起

每个命令的作用简要说明：

git diff：快速查看修改的具体内容（哪一行被修改、新增/删除了什么）；
git stash：临时保存未提交的修改，常用于“正在开发一个功能，突然需要切换到其他分支修复bug”的场景；
git fetch \-\-prune：同步远程分支的删除操作，避免本地显示已删除的远程分支。

六、常见问题解决（新手必看）#

1. 拉取/推送代码时，提示“权限不足”#

原因：未配置正确的账号密码或 SSH 密钥。

解决方法：

若用 HTTPS 地址：重新输入正确的 GitHub/GitLab 账号密码；
若用 SSH 地址：配置 SSH 密钥（网上搜索“GitHub SSH 密钥配置”，按步骤操作即可，配置一次终身可用）。

2. 合并分支时出现代码冲突#

解决方法：按前面“合并分支”部分的步骤，手动修改冲突文件，删除冲突标记，保留需要的代码，再提交即可。

注意：冲突解决后，一定要仔细检查代码，确保没有误删有用的内容。

3. 误删本地代码/误回滚版本，如何恢复？#

解决方法：执行 git reflog，查看所有操作记录，找到误删/误回滚前的版本号，再执行git reset \-\-hard 版本号，即可恢复到该版本。

4. 推送代码时，提示“本地版本落后于远程版本”#

原因：远程仓库有别人推送的最新代码，你的本地代码不是最新的，无法直接推送。

解决方法：先执行 git pull 拉取远程最新代码，解决冲突后，再执行 git push。

七、总结（核心流程梳理）#

Git 的核心操作围绕“本地仓库”和“远程仓库”展开，新手记住以下流程即可快速上手：

前期准备：安装 Git → 配置用户名和邮箱；
本地开发：初始化仓库（git init）→ 修改文件 → 提交到暂存区（git add .）→ 提交到本地版本库（git commit -m "说明"）；
多人协作：克隆远程仓库（git clone）→ 拉取远程更新（git pull）→ 创建分支开发 → 推送分支到远程（git push）→ 合并分支；
问题处理：版本回滚（git reset/git revert）、解决冲突、恢复误删代码（git reflog）。

Git 命令看似多，但常用的只有十几个，多练习几次（比如新建一个测试项目，反复执行 add、commit、push、pull 等操作），就能熟练掌握。记住：所有命令的核心都是“跟踪版本、同步代码”，理解每个命令的作用，比死记硬背更重要。

Firefly 友链自助申请按钮添加

Mon, 27 Apr 2026 00:00:00 GMT

Firefly 友链自助申请按钮添加#

本篇教程适用于 Firefly Astro 主题，不破坏原有布局、不影响任何功能，只修改两处代码，实现两种友链申请入口。

右上角「自助申请友链」按钮
友链页面内「自助申请友链」文字链接

一、准备工作#

打开你的 Firefly 项目
准备好你的 GitHub 友链申请地址

1
https://github.com/fqzlr/Firefly/issues/new?template=friend-request.yml

全程只需要修改 2 个文件，复制粘贴即可完成。

二、添加右上角「自助申请友链」按钮#

修改文件#

1
src/pages/friends.astro

步骤 1：添加申请链接#

在文件顶部的变量区域加入：

1
const friendApplyUrl = "https://github.com/fqzlr/Firefly/issues/new?template=friend-request.yml";

步骤 2：替换标题区域布局#

找到页面标题部分，替换成以下布局：

1
<div class="flex flex-col gap-4 md:flex-row md:items-end md:justify-between">
2
  <div>
3
    <div class="flex items-center gap-3 mb-3">
4
      <div class="h-8 w-8 rounded-lg bg-(--primary) flex items-center justify-center text-white">
5
        <Icon name="material-symbols:group" class="text-[1.5rem]" />
6
      </div>
7
      <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100">
8
        {title}
9
      </div>
10
    </div>
11
    {description && (
12
      <p class="text-base text-neutral-600 dark:text-neutral-400 leading-relaxed">
13
        {description}
14
      </p>
15
    )}
16
  </div>
17

18
  <!-- 自助申请友链按钮 -->
19
  <div class="flex shrink-0 flex-col items-start gap-2 md:items-end">
20
    <a
21
      href={friendApplyUrl}
22
      target="_blank"
23
      rel="noopener noreferrer"
24
      class="inline-flex items-center gap-2 rounded-lg bg-(--primary) px-4 py-2.5 text-sm font-medium text-white transition-all hover:opacity-90 hover:scale-[1.02] active:scale-[0.98]"
25
    >
26
      <Icon name="material-symbols:add-link-rounded" class="text-lg" />
27
      <span>自助申请友链</span>
28
    </a>
29
    <p class="text-xs text-neutral-500 dark:text-neutral-400 md:text-right">
30
      通过 GitHub Issue 提交，系统会自动校验回链并同步收录
31
    </p>
32
  </div>
33
</div>

展开收起

完成效果#

✅ 右上角出现美观的申请按钮
✅ 适配明暗主题
✅ 点击直接跳转到友链申请表单
✅ 不破坏任何原有布局

三、添加友链页面内文字超链接#

修改文件#

1
src/content/spec/friends.mdx

找到 Step 2 里的：

1
<p class="font-semibold text-sm mb-1">自助申请友链</p>

替换成 文字超链接样式：

1
<a href="https://github.com/fqzlr/Firefly/issues/new?template=friend-request.yml"
2
   target="_blank"
3
   class="font-semibold text-sm mb-1 inline-block text-(--primary) hover:underline">
4
  自助申请友链
5
</a>

完成效果#

✅ 保持布局完全不变
✅ 文字变为主题色超链接
✅ 鼠标悬浮自动加下划线
✅ 点击即可跳转申请

四、最终效果#

你的友链页面现在拥有：

右上角申请按钮（醒目、直观）
步骤中的文字链接（流程清晰、体验友好）

两者配合，访客可以非常方便地提交友链申请。

五、常见问题#

1. 按钮文字看不见#

这是 CSS 变量问题，可使用固定色值：

1
class="... bg-blue-500 text-white ..."

2. 跳转 404#

检查用户名、仓库名、yml 模板文件名是否正确。

3. 样式错位#

只替换教程里对应的代码块，不要改动其他结构。

六、总结#

只需修改 2 个文件：

src/pages/friends.astro → 右上角按钮
src/content/spec/friends.mdx → 文字链接

Firefly 友链自助申请自动化

Mon, 27 Apr 2026 00:00:00 GMT

Firefly 友链自助申请自动化#

Tip

原教程来自upxuu https://upxuu.com/posts/friend-link-system

这篇文章把我这次在 Firefly 里落地的“友链自助申请”方案完整拆开讲一遍。

目标很简单：

访客不需要私聊站长，直接在 GitHub 仓库里点一个 Issue 模板。
填完网站名称、网站链接、友链页面 URL 等信息后，GitHub Actions 自动开始校验。
系统会自动检查对方站点是否真的加了本站友链。
校验通过后，自动把友链写入 src/config/friendsConfig.ts。
自动格式化、自动提交、自动推送，并在 Issue 里回评结果。

如果你也想在自己的博客里做一套类似的“自助申请友链”系统，这篇文章可以直接照着抄。

一、最终效果是什么#

这套方案上线后，整个流程会变成这样：

用户打开 GitHub 仓库里的“申请友链” Issue 模板。
填写以下信息：
- 网站名称
- 网站链接
- 友链页面 URL
- 网站描述
- 网站头像 URL
用户提交 Issue。
GitHub Actions 监听到 issues.opened 事件后自动运行。
工作流先给 Issue 打上“验证中”标签。
脚本使用 Playwright 访问对方填写的友链页面。
校验两件事：
- 这个页面能不能正常打开
- 页面里有没有本站的回链
如果校验失败：
- 在 Issue 里自动评论失败原因
- 给 Issue 打上 needs-update
如果校验成功：
- 自动更新 src/config/friendsConfig.ts
- 自动运行 Biome 格式化
- 自动提交到仓库
- 自动推送到默认分支
- 在 Issue 里评论“已添加成功”
- 自动关闭 Issue

评论重新验证也支持：

如果申请者后来修好了友链页面，只需要回复这个 Issue。
Workflow 会监听 issue_comment.created。
但只有 Issue 作者本人 的评论才会触发重新验证，避免别人乱刷。

二、这套系统的核心原理#

这套自动化其实不是“一个脚本干完所有事”，而是四层拼起来的：

1. GitHub Issue 模板负责收集表单#

你不需要自己写前端表单，也不需要数据库。

GitHub 自带的 Issue Forms 就能帮你把申请信息收上来。
用户填完表单后，GitHub 会把内容渲染成一段结构化文本，放进 Issue body。

我们后面的脚本做的事情，本质上就是：

读取 context.payload.issue.body
从里面解析出“网站名称 / 网站链接 / 友链页面 URL / 描述 / 头像”

所以第一层原理很朴素：

GitHub Issue 不是单纯的“提问题”，它也可以被当成一个零后端表单系统。

2. GitHub Actions 负责事件驱动#

第二层是 GitHub Actions。

它的职责不是写业务逻辑，而是：

监听事件
准备运行环境
安装依赖
调用真正的处理脚本

这里我们监听两个事件：

1
on:
2
  issues:
3
    types: [opened, reopened]
4
  issue_comment:
5
    types: [created]

这意味着：

新建 Issue 时自动跑一次
重新打开 Issue 时自动跑一次
在 Issue 下面评论时也会跑一次

但后面脚本里会再做一层筛选，只允许作者自己的评论触发重新验证。

3. `actions/github-script` 负责把 GitHub 上下文交给本地脚本#

很多人会把全部逻辑都塞进 YAML 里的 script: |，但这样很容易炸：

YAML 缩进难维护
JS 代码太长可读性差
混入 # 注释时容易直接变成语法错误
编码和引号很容易出坑

所以这次的做法是：

Workflow 里只保留一个很短的入口。
真实逻辑放到独立文件 .github/scripts/process-friend-request.cjs。

现在入口只有这一小段：

1
- name: Process friend request
2
  uses: actions/github-script@v7
3
  with:
4
    github-token: ${{ secrets.GITHUB_TOKEN }}
5
    script: |
6
      const path = require('node:path');
7
      const handler = require(path.join(process.env.GITHUB_WORKSPACE, '.github/scripts/process-friend-request.cjs'));
8
      await handler({ github, context, core });

这段代码只做一件事：

把 github、context 这些 GitHub Runtime 对象传给仓库里的本地脚本。

于是业务逻辑就从“YAML 内联脚本”变成了“普通 Node.js 文件”，维护体验会好很多。

4. Playwright 负责做浏览器级校验#

为什么不用 fetch 直接请求页面？

因为友链页面场景更适合浏览器级校验：

有些站点会跳转
有些内容是客户端渲染出来的
有些友链列表在真实 DOM 渲染后才出现
只看 HTML 源码不一定能确认页面最终长什么样

所以这里用了 Playwright：

1
const { chromium } = require("playwright");

校验逻辑分成两步：

用浏览器打开对方提供的友链页面
检查页面内容和页面上的所有链接里，是否出现本站域名或本站名称

也就是说它不是纯字符串比较，而是近似模拟了一个真实用户打开页面之后看到的结果。

三、当前实现依赖哪些文件#

如果你要在自己的项目里复刻这套系统，主要会改下面这些文件。

1. `.github/ISSUE_TEMPLATE/friend-request.yml`#

作用：定义“申请友链”表单。

这个文件负责告诉 GitHub：

模板标题是什么
默认标签是什么
需要用户填写哪些字段

你至少要保留这些字段：

网站名称
网站链接
友链页面 URL

描述和头像可以设为可选。

2. `.github/workflows/friend-link-checker.yml`#

作用：定义自动化工作流。

它主要负责：

监听 Issue / 评论事件
安装 Node.js
安装 pnpm
安装项目依赖
安装 Playwright Chromium
调用处理脚本

这个文件是系统的“总开关”。

3. `.github/scripts/process-friend-request.cjs`#

作用：真正的核心业务逻辑。

它做了几乎所有关键工作：

解析 Issue 内容
校验 URL
使用 Playwright 检查友链页
解析现有 friendsConfig.ts
生成新的友链对象
写回配置文件
运行 Biome 格式化
Git 提交与推送
在 Issue 里评论成功/失败
打标签和关闭 Issue

可以把它理解成这套系统的“应用层”。

4. `src/config/friendsConfig.ts`#

作用：真正保存友链数据。

这个仓库不是写入 JSON，而是直接更新 TypeScript 配置文件里的数组：

1
export const friendsConfig: FriendLink[] = [
2
  {
3
    title: "站点名",
4
    imgurl: "头像地址",
5
    desc: "描述",
6
    siteurl: "https://example.com/",
7
    tags: ["Blog"],
8
    weight: 10,
9
    enabled: true,
10
    issue_id: 123,
11
  },
12
];

所以自动化脚本必须知道这个文件的格式，并按它的结构生成内容。

5. `.github/workflows/biome.yml`#

作用：保证自动写入后的文件仍然符合代码格式规范。

这一步非常重要，因为如果脚本写入的内容格式不稳定，CI 会红，自动化虽然成功写入了数据，但 PR / 提交质量检查会挂掉。

四、完整执行链路#

这里按一次“用户申请友链”的真实时间顺序讲。

第 1 步：用户提交申请#

用户点击 GitHub Issue 模板，生成一条“友链申请” Issue。

Issue body 里会包含类似下面的结构：

1
### 网站名称
2
My Blog
3

4
### 网站链接
5
https://example.com
6

7
### 友链页面 URL
8
https://example.com/friends
9

10
### 网站描述
11
记录技术与生活
12

13
### 网站头像 URL
14
https://example.com/avatar.png

这一步不需要额外后端，GitHub 自己就帮你把数据存下来了。

第 2 步：Workflow 被触发#

.github/workflows/friend-link-checker.yml 被触发。

它会在 Ubuntu Runner 上做这些准备工作：

1
- uses: actions/checkout@v4
2
- uses: actions/setup-node@v4
3
- uses: pnpm/action-setup@v4
4
- run: pnpm install --frozen-lockfile
5
- run: pnpm exec playwright install --with-deps chromium

这几步分别解决：

拉代码
提供 Node 环境
提供 pnpm
安装仓库依赖
安装 Playwright 所需浏览器

第 3 步：脚本判断这是不是友链申请#

在 process-friend-request.cjs 里，脚本首先读取：

context.eventName
context.payload.action
context.payload.issue.body

然后判断：

1
const isFriendRequest = body.includes("### 网站名称") && body.includes("### 网站链接");

如果不是友链申请，直接跳过。

这样做的好处是：

这个 workflow 可以挂在 issues 事件上
但不会误处理其他普通 Issue

第 4 步：打“验证中”标签#

如果是新建或重新打开的 Issue，先打一个标签：

1
await github.rest.issues.addLabels({
2
  owner,
3
  repo,
4
  issue_number: issueNumber,
5
  labels: ["验证中"]
6
});

这一步主要是用户体验优化。

访客一看标签，就知道系统已经开始处理，不需要站长人工回复“我看到了”。

第 5 步：解析 Issue 表单#

解析逻辑在 parseIssueBody(body)。

这个函数做了两件事：

按 Markdown 标题识别字段
容忍一些不同写法

它会兼容这些字段名称：

网站名称 / 名称 / 站点名称
网站链接 / 站点链接 / 链接 / 网址 / 地址
友链页面 / 友链地址
网站描述 / 描述 / 简介
网站头像 / 头像 / 图标
网站标签 / 标签 / 分类

这样做的意义是：

模板稍微改字，不至于整套系统失效
用户手动编辑 Issue 内容时，也更不容易把解析搞崩

解析结束后会得到一个统一结构：

1
{
2
  site_name,
3
  site_url,
4
  friend_page_url,
5
  site_desc,
6
  site_avatar,
7
  site_tag
8
}

第 6 步：先校验 URL 合法性#

在真正访问网站前，脚本先用 new URL() 规范化地址：

1
function normalizeUrl(value) {
2
  try {
3
    return new URL(value.trim()).toString();
4
  } catch {
5
    return "";
6
  }
7
}

如果用户填了无效 URL，就直接回评，不继续往后跑。

这样能省掉很多无意义的浏览器启动和网络请求。

第 7 步：用 Playwright 校验友链页面#

validateFriendPage(pageUrl) 是整个流程最关键的函数之一。

它主要做四件事：

1. 启动无头 Chromium#

1
const browser = await chromium.launch({
2
  headless: true,
3
  args: ["--no-sandbox"]
4
});

2. 打开用户提供的友链页#

1
response = await page.goto(pageUrl, {
2
  waitUntil: "domcontentloaded",
3
  timeout: 12000
4
});

3. 做失败重试#

脚本不是只试一次，而是会重试 3 次，中间等待 2 秒。

这样能降低这类波动造成的误判：

短时网络抖动
对方站点首包慢
CDN 临时超时

4. 检查是否存在本站回链#

脚本会同时抓：

页面 HTML 内容
页面所有 a[href] 链接

然后统一转成小写，检查其中是否包含：

本站域名
本站名称

当前配置里是：

1
const SITE_INFO = {
2
  name: "fqzlr",
3
  url: "https://fqzlr.com/",
4
  avatar: "...",
5
  desc: "..."
6
};

于是脚本会重点寻找：

fqzlr.com
fqzlr

如果没找到，就说明“对方站点没有把你的友链真正挂上去”，申请不会通过。

第 8 步：失败时怎么处理#

如果友链页打不开，或者没找到本站回链，脚本不会静默失败，而是自动在 Issue 里评论。

失败时会分成两类文案：

页面不可访问#

会提示：

用户填写的友链页 URL
实际访问后的 URL
HTTP 状态码
错误信息

页面可访问，但没找到本站友链#

会提示：

没找到友链
请先在对方站点添加本站信息
附上本站名称、链接、头像、描述

同时还会给 Issue 打上：

1
needs-update

这样用户只要修完，再回评论，就能重新触发验证。

第 9 步：通过后如何写入 `friendsConfig.ts`#

通过验证后，系统会进入“写配置”阶段。

这一步主要由三个函数完成：

parseFriendsConfig(content)
renderFriend(friend, indent)
updateFriendsConfig(repoRoot, data, issueId)

为什么不是直接 `JSON.parse`#

因为这个文件是 TypeScript，不是纯 JSON。

它长这样：

1
export const friendsConfig: FriendLink[] = [
2
  {
3
    title: "xxx",
4
    imgurl: "xxx",
5
    desc: "xxx",
6
    siteurl: "xxx",
7
    tags: ["Blog"],
8
    weight: 10,
9
    enabled: true,
10
    issue_id: 1,
11
  },
12
];

注意几点：

属性名没加引号
带类型标注
可能带注释
不是合法 JSON

所以脚本不能这样写：

1
JSON.parse(match[1]);

这也是之前自动化里一个会继续引发报错的坑。

当前实现怎么做#

现在的实现是：

用正则先截出 friendsConfig 数组主体
再把每个对象块拆出来
分别抽取：
- title
- imgurl
- desc
- siteurl
- tags
- weight
- enabled
- issue_id
构造成 JS 对象数组
再渲染回 TypeScript 字面量

这是一种“结构感知但不依赖 TS AST”的轻量实现。

优点是简单、无额外编译依赖。
缺点是如果你未来把 friendsConfig.ts 改成完全不同的格式，正则也得跟着改。

第 10 步：新增还是覆盖，怎么判断#

脚本会根据 siteurl 判断这是不是已存在的友链：

1
const existingIndex = friends.findIndex(
2
  (friend) => trimTrailingSlash(friend.siteurl) === normalizedUrl
3
);

这里做了去尾斜杠处理：

https://example.com
https://example.com/

会被视为同一个站点。

如果已存在：

覆盖旧项

如果不存在：

push 新项

这样可以避免重复添加同一个网站。

第 11 步：为什么写完后还要再跑 Biome#

这是这次修复里非常关键的一步。

自动脚本虽然能写出结构正确的 TS，但不一定和仓库的 Biome 格式完全一致。
结果就是：

友链添加成功了
但 biome ci ./src 报 File content differs from formatting output

为了解决这个问题，我在脚本里加了一层：

1
formatFriendsConfig(repoRoot);

它会调用仓库自己的 Biome 可执行文件：

1
node_modules/.bin/biome

然后执行：

Terminal window

1
biome format --write src/config/friendsConfig.ts

这样自动生成的提交就会和仓库 CI 的格式要求一致。

这是把“写入成功”升级成“写入成功且能过 CI”的关键。

第 12 步：自动提交与推送#

通过验证并写入配置后，脚本会自动执行 Git 流程：

1
git config user.name "github-actions[bot]"
2
git config user.email "github-actions[bot]@users.noreply.github.com"
3
git add src/config/friendsConfig.ts
4
git commit -m "🤝 更新友链: 站点名"
5
git pull --rebase origin <default-branch>
6
git push origin HEAD:<default-branch>

这里有两个值得注意的点。

1. 为什么先 `pull --rebase`#

因为仓库有可能在 workflow 运行期间又被其他人提交了新内容。
如果直接 push，很容易出现：

1
! [rejected] master -> master (fetch first)

先 pull --rebase 可以降低这种失败概率。

2. 为什么不是强推#

自动化流程里不应该默认 --force。
因为它是服务流程，不是人工兜底流程。强推会增加误覆盖风险。

第 13 步：评论成功结果并关闭 Issue#

自动提交成功后，脚本还会回到 GitHub 上收尾：

评论“已成功添加友链”
移除“验证中”
移除 needs-update
关闭 Issue

关闭时使用的是：

1
await github.rest.issues.update({
2
  owner,
3
  repo,
4
  issue_number: issueNumber,
5
  state: "closed",
6
  state_reason: "completed"
7
});

这里要注意：

state 必须是 "closed"
不能写成 "completed"

completed 是 state_reason，不是 state

这也是这次修复里顺手纠正的一个 API 用法问题。

五、这次真正需要改哪些代码#

如果你也要照着搭一套，最少要改下面这些地方。

1. 修改 Issue 模板#

文件：

1
.github/ISSUE_TEMPLATE/friend-request.yml

你要根据自己的站点信息调整：

模板标题
默认标签
表单字段
“请先添加本站友链”的提示文案

如果你站点不是博客，还可以加更多字段，比如：

RSS 链接
站点分类
站长昵称
是否接受头像热链

2. 修改站点常量#

文件：

1
.github/scripts/process-friend-request.cjs

重点修改这里：

1
const SITE_INFO = {
2
  name: "fqzlr",
3
  url: "https://fqzlr.com/",
4
  avatar: "https://q1.qlogo.cn/g?b=qq&nk=20447289&s=640",
5
  desc: "坐而言不如起而行."
6
};

这是整个校验逻辑里“本站信息”的唯一可信来源。

它会影响：

是否判断回链存在
失败时给用户展示的本站友链信息

3. 修改友链数据文件路径#

如果你的友链配置不在当前路径，需要改这里：

1
const FRIENDS_CONFIG_RELATIVE_PATH = "src/config/friendsConfig.ts";

如果你用的是：

friends.json
data/friends.ts
src/content/friends.yaml

那解析和写入逻辑也要跟着改。

4. 修改配置文件字段映射#

当前脚本写入的是这个结构：

1
{
2
  title,
3
  imgurl,
4
  desc,
5
  siteurl,
6
  tags,
7
  weight,
8
  enabled,
9
  issue_id
10
}

如果你的项目使用的是别的字段，比如：

name
url
avatar
description

那就要同步调整：

parseFriendsConfig
renderFriend
updateFriendsConfig

这三个函数。

5. 修改 Workflow 权限#

当前 workflow 需要：

1
permissions:
2
  contents: write
3
  issues: write

原因是：

contents: write 用来提交代码
issues: write 用来评论、打标签、关闭 Issue

如果权限不够，会表现成：

能跑脚本
但不能回评
或者不能 push

6. 确保依赖安装方式和仓库一致#

这次还修了一组很典型的 CI 坑。

`pnpm/action-setup` 版本冲突#

如果你的 package.json 已经有：

1
"packageManager": "pnpm@9.14.4"

那么 workflow 里不要再写：

1
with:
2
  version: 9

否则会出现：

1
Multiple versions of pnpm specified

Biome 命令找不到#

不要依赖“全局有 biome 命令”。

更稳的方式是：

1
pnpm install --frozen-lockfile
2
pnpm exec biome ci ./src --reporter=github

这样 CI 使用的一定是仓库锁定的 Biome 版本。

六、为什么我把长逻辑挪出了 YAML#

这是这次改动里最值得保留的一个经验。

一开始如果把全部逻辑都写在：

1
script: |
2
  ...

里面，会有这些真实问题：

代码太长，维护困难
YAML 和 JS 的双层语法混在一起，调试痛苦
混入 # 注释时会直接触发 SyntaxError
编码、引号、缩进很容易造成“看起来没问题，运行就炸”

所以我最后采用的是：

Workflow 里只保留短入口
真正逻辑写进 .cjs 文件

这也是我给所有 GitHub Actions 复杂逻辑的建议：

YAML 负责调度，脚本文件负责业务。

不要让 YAML 同时承担“编排器”和“应用层代码容器”的职责。

七、这一套方案有哪些限制#

这套实现已经够实用，但它不是没有边界。

1. `friendsConfig.ts` 解析依赖当前格式#

现在是用正则和对象块拆分来处理 TS 配置。

所以如果你未来把友链配置改成：

嵌套更深
动态表达式更多
多行模板字符串
复杂注释结构

那解析函数需要一起升级。

更稳的长期方案有两个：

改成单独的 JSON / YAML 数据文件
用 TypeScript AST 或 Babel AST 解析

2. Playwright 校验是“近似真实浏览器”，但不是 100% 万能#

比如：

站点有地区限制
站点会拦 GitHub Actions Runner IP
页面需要登录
友链列表要滚动或点击后才出现

这些情况下仍可能误判。

如果你的网站遇到这种场景，可以进一步增强：

增加自定义等待策略
支持指定 CSS 选择器
支持截图附件
把失败截图上传到 Issue 评论

3. 自动 push 依赖仓库分支策略#

如果你的默认分支启用了非常严格的限制，比如：

不允许 GitHub Actions 写入
必须走 PR 合并
强制签名提交

那么脚本里的“直接提交并推送”就需要改造。

你可以改成：

自动创建分支
自动提交到新分支
自动开 PR

这样会更适合协作型仓库。

八、如果你要从零搭建，推荐照这个顺序做#

如果你不是在改现有项目，而是从零上手，我推荐按下面顺序来。

第 1 步：先确定友链数据存储格式#

先决定你最终要写入哪里：

JSON
YAML
TS 配置文件

这一步会直接决定后面脚本复杂度。

如果想最省事，我建议优先 JSON 或 YAML。
如果你已经有成熟的 TS 配置结构，也可以像 Firefly 这样继续沿用。

第 2 步：先把 Issue 模板做好#

不要一上来就写脚本。
先确保用户提交的内容结构稳定。

因为自动化流程的第一输入，其实就是 Issue body。

第 3 步：先做“只解析不写入”#

先写一个最小脚本，只做：

读取 Issue 内容
解析字段
在日志里打印结果

这样先确认字段提取没问题，再往后接浏览器校验和写文件。

第 4 步：接入 Playwright 校验#

等字段解析稳定后，再加：

URL 检查
页面是否可访问
页面里是否包含本站回链

不要一开始把所有事情混在一块写，不然后期很难排错。

第 5 步：最后再接 Git 提交#

真正危险的是自动提交阶段。
我建议把“解析”和“校验”完全确认稳定后，再开放：

写文件
git add
git commit
git push

否则一开始就自动 push，调试时很容易把仓库历史搞脏。

九、这次踩过的坑，顺手给你避掉#

这里把这次实际遇到的问题总结一下。

1. `actions/github-script` 里的 JS 不是 Shell#

script: | 里面只能写 JS，不能混进：

1
# 注释

这种 Shell 风格注释。
否则会直接触发：

1
SyntaxError: Invalid or unexpected token

2. TS 配置文件不能直接 `JSON.parse`#

friendsConfig.ts 是 TypeScript 对象字面量，不是 JSON。

只要你文件里有：

类型标注
非引号属性名
注释

它就不可能直接被 JSON.parse。

3. 自动写入后的文件必须再格式化#

脚本“能写进去”不等于“能过 CI”。

格式化是必须的，不是锦上添花。

4. `pnpm/action-setup` 和 `packageManager` 不能双重声明版本#

如果 package.json 已经写了：

1
"packageManager": "pnpm@9.14.4"

workflow 里就不要重复写 version。

5. Cloudflare 机器人会检查 `wrangler.jsonc` 的 Worker 名称#

如果你的项目名已经改成 firefly，但 wrangler.jsonc 里还是：

1
"name": "fuwari"

Cloudflare 的机器人 PR 会持续提醒你更新。

所以这次也顺手把：

1
"name": "fuwari"

改成了：

1
"name": "firefly"

十、我对这套方案的建议#

如果你只是个人博客，这套方案已经够用，而且很优雅：

没有数据库
没有后端服务
没有额外部署成本
审核门槛低
自动化程度高

它利用的其实都是 GitHub 现成能力：

Issue Forms
Actions
github-script
仓库写权限

再加上一个 Playwright，就能拼出相当完整的业务闭环。

如果你以后还想继续增强，我建议优先加这几项：

失败时自动截图并贴到评论
自动创建 PR，而不是直接推默认分支
将友链数据迁移到单独的 JSON / YAML 文件
支持白名单域名 / 黑名单域名
支持自动去重、自动排序、自动补充默认头像

十一、本文对应的关键文件清单#

方便你对照仓库直接看：

.github/ISSUE_TEMPLATE/friend-request.yml
.github/workflows/friend-link-checker.yml
.github/scripts/process-friend-request.cjs
src/config/friendsConfig.ts
.github/workflows/biome.yml
wrangler.jsonc

十二、结语#

这套“友链自助申请”方案本质上是把 GitHub 当成了一个轻量业务平台来用：

用 Issue 表单承接输入
用 Actions 承接流程
用脚本承接业务判断
用仓库文件承接数据落地

没有后端，也能把流程做完整。
对个人博客和轻量站点来说，这种思路非常值。

如果你正在做自己的博客系统，或者想把原本人工处理的流程逐步自动化，我很推荐从这种“基于 Git 仓库自身能力”的方案开始搭。

怎么使用obsidian 来编写 astro 博客

Sat, 18 Apr 2026 00:00:00 GMT

Obsidian + Astro Composer + Git 插件同步 Astro 博客到 GitHub 完整教程

前置前提（必做）：

已安装 Obsidian 客户端，且启用「第三方插件」（设置 → 第三方插件 → 关闭“安全模式”）。
已创建 Astro 博客项目（本地需有 Astro 项目文件夹，可通过 pnpm create astro@latest 快速创建，选择 blog 模板即可），并熟悉 Astro 项目的 src/content 目录（用于存放博客文章）。
已注册 GitHub 账号，且创建了用于托管 Astro 博客的仓库（建议仓库名与 Astro 博客项目名一致，若要部署 GitHub Pages，仓库名可设为 用户名.github.io）。
已安装所需插件：Astro Composer（Obsidian 插件）、Git（Obsidian 插件，常用 Obsidian Git 或 Git Vault/Folder Sync，本教程以 Obsidian Git 为例，适配多数用户需求）。

第一步：安装并配置 Astro Composer 插件（核心：Obsidian 笔记转 Astro 内容）#

Astro Composer 是 Obsidian 与 Astro 博客无缝衔接的关键插件，可自动将 Obsidian 笔记转换为 Astro 支持的 Markdown 格式（含自动处理链接、标准化属性、管理草稿等），目前该插件暂未上架 Obsidian 社区插件库，需通过 BRAT 插件安装或手动安装，推荐 BRAT 安装（更便捷，支持自动更新）。

1.1 安装 Astro Composer 插件#

先安装 BRAT 插件：Obsidian 内 → 设置 → 第三方插件 → 浏览社区插件 → 搜索「BRAT」→ 安装并启用。
启用 BRAT 后，打开 BRAT 设置 → 点击「Add a beta plugin」→ 输入 Astro Composer 插件仓库地址（https://github.com/astro-modular/astro-composer）→ 点击「Add Plugin」，等待安装完成后启用插件。

1.2 配置 Astro Composer 插件#

配置核心目的：让插件知道「Obsidian 笔记存放位置」和「Astro 项目的内容目录位置」，实现笔记自动转换后同步到 Astro 项目中。

打开 Obsidian 设置 → 找到「Astro Composer」插件，进入配置页面。
image.png

image.png

image.png
核心配置项（必设）：
1. Posts Folder：设置 Obsidian 中用于存放博客文章的文件夹（例如 Blog/Posts），后续所有要发布的笔记都放在这个文件夹下。
2. Astro Content Path：设置本地 Astro 项目的src/content 目录路径（例如 D:/MyBlog/astro-blog/src/content），插件会自动将转换后的笔记同步到这个目录。
3. Link Base Path：设置链接基准路径，填写 Astro 博客的文章访问路径（例如 /blog），插件会自动将 Obsidian 内部链接（ wikilinks 或 Markdown 内部链接）转换为 Astro 友好的链接格式，避免发布后链接失效。
4. Creation Mode：选择文章存储结构，推荐「Folder-based with index.md」（每个文章对应一个文件夹，内部包含 index.md 文件），适配多数 Astro 博客模板。
5. Draft Management：启用「Underscore Prefix」，插件会为草稿笔记添加下划线前缀（例如 _my-draft.md），Astro 会自动隐藏这些草稿，避免误发布。
可选配置（优化体验）：
1. Property Standardization：设置笔记属性模板（例如标题、日期、标签等），启用「Standardize Properties」命令，可自动为笔记添加缺失的属性，保持 Astro 文章格式统一。
2. Rename Post Command：启用后，修改笔记的「title」属性，插件会自动将笔记文件名/文件夹名更新为 kebab-case 格式（例如“我的第一篇博客”→「my-first-blog」），适配 Astro 的路由规则。
配置完成后，点击「Save Settings」，重启插件（Obsidian 重启或禁用再启用），确保配置生效。

Simple Guides for Mizuki

Mon, 01 Apr 2024 00:00:00 GMT

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts#

1
---
2
title: My First Blog Post
3
published: 2023-09-09
4
description: This is the first post of my new Astro blog.
5
image: ./cover.webp
6
tags: [Foo, Bar]
7
category: Front-end
8
draft: false
9
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`pinned`	Whether this post is pinned to the top of the post list.
`priority`	The priority of the pinned post. Smaller value means higher priority (0, 1, 2…).
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post. 1. Start with `http://` or `https://`: Use web image 2. Start with `/`: For image in `public` dir 3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`licenseName`	The license name for the post content.
`author`	The author of the post.
`sourceLink`	The source link or reference for the post content.
`draft`	If this post is still a draft, which won’t be displayed.

Where to Place the Post Files#

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.webp
5
    └── index.md

Encrypted Post

Mon, 15 Jan 2024 00:00:00 GMT

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts#

1
---
2
title: My First Blog Post
3
published: 2023-09-09
4
description: This is the first post of my new Astro blog.
5
image: /src/assets/images/cover.avif
6
tags: [Foo, Bar]
7
category: Front-end
8
draft: false
9
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`pinned`	Whether this post is pinned to the top of the post list.
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post. 1. Start with `http://` or `https://`: Use web image 2. Start with `/`: For image in `public` dir 3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`alias`	alias for the post. The post will be accessible at `/posts/{alias}/`. Example: `my-special-article` (will be available at `/posts/my-special-article/`)
`licenseName`	The license name for the post content.
`author`	The author of the post.
`sourceLink`	The source link or reference for the post content.
`draft`	If this post is still a draft, which won’t be displayed.
`encrypted`	Whether this post is password protected.
`password`	The password to unlock the encrypted post.
`passwordHint`	A hint to help users remember the password. Displayed below the password input.

Where to Place the Post Files#

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

Posts alias#

You can set a alias for any post by adding the alias field to the front-matter:

1
---
2
title: My Special Article
3
published: 2024-01-15
4
alias: "my-special-article"
5
tags: ["Example"]
6
category: "Technology"
7
---

When a alias is set:

The post will be accessible at the custom URL (e.g., /posts/my-special-article/)
The default /posts/{slug}/ URL will still work
RSS/Atom feeds will use the custom alias
All internal links will automatically use the custom alias

Important Notes:

Alias should NOT include /posts/ prefix (it will be added automatically)
Avoid special characters and spaces in alias
Use lowercase letters and hyphens for best SEO practices
Make sure alias are unique across all posts
Don’t include leading or trailing slashes

How It Works#

graph LR A[User Password] --> B[Direct AES Decryption] B --> C{Check Prefix?} C -- "MIZUKI-VERIFY:" found --> D[Success: Render Content] C -- Random/Garbage --> E[Fail: Wrong Password]

Page Encryption#

You can password protect any post by setting encrypted: true and providing a password in the front-matter:

1
---
2
title: My Private Post
3
published: 2024-01-15
4
encrypted: true
5
password: "my-secret-password"
6
passwordHint: "Hint: The password is my dog's name"
7
---

Fields#

Field	Required	Description
`encrypted`	Yes	Set to `true` to enable password protection
`password`	Yes	The password to unlock the post
`passwordHint`	No	A hint displayed below the password input to help users

How the Unlock Box Looks#

The unlock box displays:

A lock icon in the theme’s primary color
The post title “Password Protected”
A description asking for the password
A hint (if passwordHint is provided)
A password input field and unlock button

After entering the correct password, the content is decrypted and displayed. The password is stored in session storage so users don’t need to re-enter it on subsequent page loads within the same session.

Include Video in the Posts

Mon, 01 Aug 2022 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

1
---
2
title: Include Video in the Post
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube#

Bilibili#

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

Markdown 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

***