一枚十年域名：我把博客从 Typecho 搬到了 Astro

#寻常#Cloudflare Pages#Astro 共 1,860 字 约 6 分钟

2026 年 4 月 19 日，我在 Spaceship 购入了一枚特殊的域名：20260419.xyz，一口气续了十年有效期。 它不只是一个简单的网络地址，更像一枚属于自己的时间胶囊——定格当下，记录思考，通向遥远的未来。

这篇文字，既是新博客的第一篇正式随笔，也是一次完整的技术复盘。我是如何一步步从动态博客的繁琐维护中抽身，最终选择 Astro，完成整套静态博客的部署。

为什么放弃动态博客？

在接触 Astro 之前，我陆续折腾过 Typecho、Halo 和 WordPress几款主流博客程序。

它们各自都有成熟完善的生态，但长期使用下来，我渐渐感受到动态系统绕不开的负担：维护成本过高。

  • 挥之不去的数据焦虑：所有文章内容都存储在数据库中。每一次迁移，都要导出 SQL、搬运文件、调整配置，稍有疏忽就可能出现错乱，甚至丢失内容。
  • 不必要的性能开销：页面动态渲染、数据库频繁查询、后端服务持续运行……对于一个只用来记录文字的博客而言，整套体系显得格外沉重。
  • 持续存在的安全风险：只要涉及 PHP、Java、MySQL，就要时刻留意版本更新、漏洞补丁，需要花费精力处理各类安全问题。

我想要的，仅仅是一处可以安安静静写字的空间，而不是一个需要时刻操心运维的服务器。也正因如此，我开始将目光投向静态博客方案。

为什么最终选择了 Astro？

权衡对比之后，我敲定了 Astro。它精准面向内容站点打造，静态博客带来的优势，对我而言几乎是压倒性的：

  1. 数据安全，版本控制：文章本身就是纯粹的 Markdown 文件，存放在 GitHub 仓库之中。每一次修改都会留下版本记录。就算日后更换主题、迁移平台，只要 .md 文件还在，我的文字就不会消失。
  2. 出众的访问速度：输出全部为静态资源，搭配 Cloudflare Pages 的边缘网络，无需服务端实时渲染，能够获得很低的全球访问延迟。
  3. 近乎为零的维护成本：没有数据库，没有常驻后端运行时。不必担心各类漏洞扫描，也不需要高价服务器维持运行。
  4. 友好的开发体验：作为开发者，可以用代码掌控博客的方方面面，本地 pnpm dev 的热更新开发体验也十分顺滑。

部署踩坑实录（Cloudflare Pages + pnpm）

本次部署使用的是 astro-whono 主题，托管平台为 Cloudflare Pages，包管理器使用 pnpm。这里记录下部署过程中遇到的关键问题与对应解决方案，方便后续参考，也给同样踩坑的人提供一份借鉴。

1. pnpm 构建脚本拦截（esbuild）

这是非常常见、也很容易让人摸不着头脑的一处问题。Cloudflare Pages 的构建环境，或是本地 pnpm 的默认策略，会拦截部分依赖包的构建脚本。

报错信息：

plaintext
UTF-8|1 Line|
ERR_PNPM_IGNORED_BUILDS Ignored build scripts: esbuild@0.28.2

解决方案：

需要在项目根目录的 .pnpmrc 文件中显式声明允许构建的依赖：

ini
UTF-8|1 Line|
only-built-dependencies[]=esbuild

或者在交互终端中执行：

Bash
UTF-8|2 Lines|
pnpm approve-builds
# 勾选 esbuild 并回车

2. 图标库导入路径变更（@lucide/astro）

主题代码使用了较新的 Lucide 图标导入方式，但本地安装的版本可能滞后或不兼容子路径导出。

报错信息：

plaintext
UTF-8|1 Line|
Failed to resolve import "@lucide/astro/icons/trash-2"

解决方案：

不要使用子路径导入，改为统一的命名导入方式。修改 src/components/admin/AdminIcon.astro：

diff
UTF-8|3 Lines|
- import Trash2 from '@lucide/astro/icons/trash-2';
- import Settings from '@lucide/astro/icons/settings';
+ import { Trash2, Settings } from '@lucide/astro';

3. 缺失关键依赖（yaml & sharp）

Astro 在处理 Frontmatter 和图片优化时需要这两个包，但有时不会自动安装。

报错信息：

plaintext
UTF-8|2 Lines|
Failed to resolve import "yaml"
MissingSharp: Could not find Sharp.

解决方案：

手动安装即可：

Bash
UTF-8|1 Line|
pnpm add yaml sharp

4. 环境变量与站点配置

为了让 RSS、Sitemap 和 SEO 标签正常工作，必须正确设置 SITE_URL。

关键点：

在 Cloudflare Pages 的 Environment variables 中设置：

ini
UTF-8|2 Lines|
SITE_URL=https://20260419.xyz
NODE_VERSION=26.12.1

同时在 astro.config.mjs 中引用它（项目已通过 site.config.mjs 封装）：

JavaScript
UTF-8|9 Lines|
import { site } from './site.config.mjs';

export default defineConfig({
  site: site.url,
  output: 'server',
  adapter: cloudflare({
    platformProxy: { enabled: true }
  }),
});

完整部署流程总结

  1. 本地开发调试：pnpm install → pnpm dev → 在此基础上撰写、编辑文章。
  2. 本地构建验证：pnpm build，确认构建过程无报错。
  3. 推送代码仓库：git push 将完整代码推送到 GitHub 对应仓库。
  4. 平台自动构建：Cloudflare Pages 监听 main 分支，触发拉取代码与自动构建部署。
  5. 绑定自定义域名：在 Cloudflare 后台添加自定义域名 20260419.xyz。

结语

从 Typecho 迁移至 Astro，不只是换了一套博客程序，更是一次思路的转变：告别动态系统繁杂的运维，拥抱静态文件带来的简单与踏实。

20260419.xyz 就此正式启航。接下来的十年，希望这片小小的空间，可以沉淀下更多值得记录的思考与文字。

部署环境信息：

  • Framework：Astro 7.3.1
  • Adapter：@astrojs/cloudflare
  • Platform：Cloudflare Pages
  • Package Manager：pnpm 11.x
  • Node Version：22.22.0

评论