全部文章

2026 个人独立博客零基础建站指南:EmDash CMS + Cloudflare Workers 实战

告别传统服务器运维,也不必每次写文章都手动推代码。本文以福来吧(ful8.net)的真实建站过程为例,手把手记录如何用 Astro 生态的 EmDash CMS 配合 GitHub、Cloudflare Workers、D1 数据库与 R2 图床,低成本搭建一套高速、现代、自带后台的个人独立博客。

屏幕上的建站代码

2026 年重新注册回 ful8.net 这个陪伴过我十多年的老域名后,我面临的第一个问题就是:现在建一个个人博客,该选什么程序?

早年折腾独立博客,无非两种路线:

  1. 传统动态 CMS(如 WordPress):后台写文章很方便,但得自己买 VPS、配环境、管安全更新、扛垃圾流量,折腾久了很耗精力。
  2. 纯静态生成器(如 Hugo / Hexo / Astro 纯静态):托管在边缘网络上极快、几乎零维护,但每次改个错别字、传张图片都要在本地打开编辑器写 Markdown、跑命令、推 Git,手机上想临时记点东西很不顺手。

直到我遇到 EmDash CMS——一个基于 Astro 7 + TypeScript 的全栈开源 CMS,天然支持部署在 Cloudflare Workers + D1 + R2 上。它既保留了边缘渲染的极速体验,又自带一套非常干净的现代化后台(/_emdash/admin)、全文搜索、RSS 订阅、分类标签和评论系统。

这篇文章就是 福来吧(ful8.net) 的完整建站实战记录,帮你少走弯路,一次上线成功。

一、整体架构与准备工作

在动手之前,先看一眼这套方案的组成,非常清爽:

  • 博客框架:EmDash CMS(底层为 Astro + React 后台)
  • 代码托管:GitHub(私有仓库即可,推送即触发自动部署)
  • 运行环境:Cloudflare Workers(全球边缘节点运行,免运维服务器)
  • 数据库:Cloudflare D1(存文章、栏目、评论、站点设置与后台会话)
  • 媒体图床:Cloudflare R2(存文章图片,绑定自定义域名走 CDN 加速)

本地环境准备

开始前确保本机准备好以下基础环境:

  1. Node.js >= 22.23.4(避坑提示:Astro 7 对 Node 22 的小版本有明确要求,低于 22.23.4 会直接报错,建议用 nvm 安装并使用 22.23.5 或更高版本,在项目根目录建一个 .nvmrc 文件锁定版本)。
  2. pnpm:包管理器,安装速度快且省磁盘。
  3. GitHub 账号 与 Cloudflare 账号(并提前把域名托管到 Cloudflare DNS)。

二、初始化 EmDash 博客项目

在本地新建并进入你的项目目录,直接运行 EmDash 官方脚手架初始化 Cloudflare 博客模板:

pnpm create emdash@latest . --template cloudflare:blog --yes

脚手架会自动完成以下几件事:

  • 生成 Astro + EmDash 博客模板(自带首页、文章页、栏目页、标签页、全文搜索页与 RSS 源)。
  • 在项目根目录生成一个 .env 文件,里面包含随机生成的 EMDASH_ENCRYPTION_KEY(切记不要提交到 Git)。
  • 预置 astro.config.mjs、wrangler.jsonc、src/worker.ts 与 seed/seed.json。

安装完成后,可以在本地先跑一下开发服务器:

pnpm dev

此时打开 http://localhost:4321 就能看到本地运行的博客(Wrangler 会自动在 .wrangler/ 目录下模拟本地 D1 和 R2,无需连接线上资源)。

三、规划站点栏目与中文化定制

默认模板是英文的,上线中文博客前建议做好三处定制:

1. 修改 seed/seed.json 预设栏目与导航

EmDash 首次在空数据库启动时,会自动读取 seed/seed.json 初始化站点名称、栏目、导航菜单和首发内容。

以福来吧为例,我把全站精简为 4 个核心栏目(对应 taxonomies 中的 category):

  • ai-tools:AI工具
  • guides:玩机教程
  • finds:资源情报
  • blog:站长碎念

同时把主导航 menus.primary、署名 bylines(站长「福来」)和默认简介都改成中文,这样线上第一次启动就能直接拥有完整的站点骨架。

2. 优化中文字体与站点域名

在 astro.config.mjs 中补上你的正式域名 site,并给正文字体加上常见的中文系统无衬线回退栈,确保 Windows 和 macOS 下中文排版都足够清爽:

export default defineConfig({
	site: "https://ful8.net",
	output: "server",
	fonts: [
		{
			provider: fontProviders.google(),
			name: "Inter",
			cssVariable: "--font-body",
			weights: [400, 500, 600, 700],
			fallbacks: [
				"PingFang SC",
				"Hiragino Sans GB",
				"Microsoft YaHei",
				"sans-serif",
			],
		},
	],
});

3. 本地化日期与界面文案

  • 将 src/layouts/Base.astro 的 lang 默认值改为 "zh-CN",并补充站点的 <meta name="keywords" />。
  • 将 src/utils/locale.ts 的默认日期格式改为 "zh-CN"。
  • EmDash 模板自带的 src/utils/reading-time.ts 已经内置了中日韩(CJK)字符计数,只需把输出文案从 min read 改为 约 X 分钟阅读 即可。

四、在 Cloudflare 创建 D1 数据库与 R2 图床

打开 Cloudflare 控制台,手动创建两个核心存储资源:

  1. 创建 D1 数据库:进入 Storage & Databases → D1 SQL Database,新建数据库(例如命名为 d1-ful8-net),复制生成的 Database ID。
  2. 创建 R2 存储桶:进入 R2 Object Storage,新建存储桶(例如命名为 r2-ful8-net)。
  3. 给 R2 绑定自定义域名(强烈推荐):在 R2 存储桶的 Settings → Custom Domains 中绑定一个图片二级域名(例如 img.ful8.net)。这样上传的图片会直接通过 Cloudflare 全球 CDN 分发,不消耗 Worker 计算资源。

更新 wrangler.jsonc 与 astro.config.mjs

将你创建的数据库名、Database ID 和 R2 桶名填入 wrangler.jsonc:

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "ful8-net",
	"main": "./src/worker.ts",
	"compatibility_date": "2026-02-24",
	"compatibility_flags": ["nodejs_compat"],
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "d1-ful8-net",
			"database_id": "粘贴你的-D1-Database-ID"
		}
	],
	"r2_buckets": [
		{
			"binding": "MEDIA",
			"bucket_name": "r2-ful8-net"
		}
	],
	"triggers": {
		"crons": ["* * * * *"]
	}
}

然后在 astro.config.mjs 中给 r2() 加上 publicUrl,指向你刚才绑定的图床域名:

integrations: [
	react(),
	emdash({
		database: d1({ binding: "DB", session: "auto", coalesce: true }),
		storage: r2({
			binding: "MEDIA",
			publicUrl: "https://img.ful8.net",
		}),
	}),
],
常见疑问:需要手动创建 KV 命名空间吗?不需要。EmDash 自身的用户会话和内容全部存在 D1 中。虽然 @astrojs/cloudflare 会在构建时自动声明一个 SESSION KV 绑定(用于 Astro 内置的 Session API),但 Wrangler v4 部署时会自动创建并绑定,无需手动干预。

五、推送到 GitHub 并配置自动部署

1. 检查 .gitignore 防止密钥泄露

推送代码前,务必确认 .gitignore 已经排除了以下文件:

  • .env / .env.* / .dev.vars(绝对不能推到 GitHub!)
  • .wrangler/、dist/、.astro/、node_modules/、data.db*、.DS_Store

建议在 GitHub 创建一个 Private(私有仓库),然后把代码推送上去:

git add .
git commit -m "Initial EmDash blog for ful8.net"
git remote add origin https://github.com/<你的用户名>/<你的仓库名>.git
git push -u origin main

2. 在 Cloudflare Workers 关联 GitHub

进入 Cloudflare 控制台 → Workers & Pages → Create → Continue with GitHub,选择你的仓库,填入以下关键配置:

  • Worker Name:与 wrangler.jsonc 中的 name 保持一致
  • Build command:pnpm build
  • Deploy command:npx wrangler deploy
  • Build Variables(构建环境变量)非必需:新增 NODE_VERSION = 22.23.5

3. 配置线上加密密钥(关键一步)

部署创建完成后,进入该 Worker 的 Settings → Variables and Secrets,新增一条 Secret(加密变量):

  • 变量名:EMDASH_ENCRYPTION_KEY
  • 变量值:复制本地 .env 文件里的 EMDASH_ENCRYPTION_KEY 值即可。

最后在 Settings → Domains & Routes 中绑定你的主域名(如 ful8.net),等待证书自动签发完毕,站点就正式上线了。

六、上线后的必做清单与踩坑备忘

网站能打开后,别急着关页面,花 5 分钟把这几件事收尾:

  1. 完成后台初始化:访问 https://你的域名/_emdash/admin,按提示注册 Passkey 管理员账号。首次访问时,EmDash 会自动执行 D1 数据库迁移并导入 seed/seed.json 的栏目与内容。
  2. 开启评论审核:EmDash 博客模板默认开启文章评论,上线后记得在后台开启评论审核,防止垃圾评论骚扰。
  3. 测试图床上传:在后台上传一张测试图片,确认图片 URL 已经是 https://img.ful8.net/...。
  4. 本地开发小坑备忘:本地运行 pnpm dev 时,如果中途修改了 astro.config.mjs,终端可能会报 Expected exportTypes to be defined / server restart failed。这不是代码写错了,只是 Cloudflare 本地模拟器不支持热重启,按 Ctrl + C 停止后再重新运行 pnpm dev 即可。

最后

从初始化项目到绑定自定义域名、接入 R2 图床和 GitHub 自动部署,整套流程跑下来比传统配服务器省心太多。以后改主题推一下 Git 就能自动上线,日常写文章直接登录 /_emdash/admin 后台即可。

接下来我会在「玩机教程」和「站长碎念」栏目继续分享 老域名重启 SEO 避坑指南 以及 福来吧的后续折腾笔记,欢迎订阅本站 RSS(/rss.xml)一起交流。

评论交流

No comments yet