从hugo迁移至astro

Jul 30, 2025

Tags:

前言

Move from hugo to astro. Deploy to cloudflare workers without git.

从wordpress迁移到hugo一周后，我面临了两个难题(折腾的理由)。

不易使用

灵活的使用现代美观的内容不容易

不易修改

模板改起来还是要用前端方法

是的，这是一个mdx文件，上面两张卡片是starlight的内置组件。

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="不易使用" icon="open-book">
    灵活的使用现代美观的内容不容易
  </Card>
  <Card title="不易修改" icon="information">
    模板改起来还是要用前端方法
  </Card>
</CardGrid>

用hugo+bootstrap也能实现，方法是shortcode，但是用起来不直观，bootstrap本身也是一个html+css+js的框架。如果要用类似docsy这样的框架，还是需要学习前端的知识，还不如：

尝试

要上这艘大船真的不容易！（对于没有前端开发经验的人来说）

hugo或zola的逻辑特别简单，尤其是hugo，下载hugo，下载主题，把md文件丢进content目录就可以了。

我用同样的逻辑搞astro，就感觉很不对劲，用老办法（把md丢进content）页面没有反应，日志都列不出来。试图在网络搜索，竟然没有人提到这些看上去很傻很简单的问题。在走了几天弯路之后，硬着头皮去看官方文档(RTFM，根据经验很多问题仔细读文档就能解决)，在学习了官方教程之后，我终于恍然大悟！

hugo视角：网站是一堆素材，而hugo是一个exe二进制工具，能把素材转化成网页，用起来可简可繁，大部分主题只要填充md就能用起来。

Astro视角：网站本质上是一个node项目，而astro是一个node.js包，或者叫框架，并没有内建任何建站规则。所以，需要使用者掌握基础的js项目运行逻辑方可使用。

说人话：astro相对于hugo是手动挡的跑车，而hugo的自动挡也非常好用。哪个更强？我不知道，但开启手动挡的感觉真不错。

为什么简单的问题没有答案，因为astro的大部分开发者和模板提供者都默认使用者具备前端开发能力，没有提供像很多hugo模板的starter解决方案，主题下载之后，需要自己手动修改首页或列表页的逻辑业务代码才能使用，这些问题在开发者看起来太简单了，但对于普通用户真难。这限制了astro的发展，同时创造了商机！我看到有一些网站在提供astro建站服务。

回来说正题，官方教程完整的引导了整个基础网站运行的逻辑，让只会一点html的我也能理解。之后，再使用模板进行修改，就容易的多了！

文档主题能做blog吗？

是的，starlight是一个文档主题，主营业务是docs。

但，她也是astro唯一的官方主题！自带滚动TOC，自带响应式布局（就是手机或电脑能自动调整，不同界面看着都舒服），顶栏侧栏底栏都能定制，自带一些在好用的组件。Lighthouse四个100分！

文档和网志的主要区别：

文章发表时间的显示；
前后页面的链接显示；
侧栏的组织。

这些被starlight-blog插件给解决了，虽然不是很美观，但是随着对astro的熟悉，改起来应该不难。

在hugo的宇宙里，也有类似的docsy。

迁移的过程

目标还是和之前每次的迁移一样，url需要完整保留，基础功能和文件不丢。

安装astro和官方主题starlight
Terminal window
```
brew install node
npm create astro@latest
```
第一步选择路径，第二步选择文档主题starlight，github功能我没有用
安装starlight-blog插件
```
npm -i starlight-blog
npm install
npm run dev
```
这个主题新建站的话特别简单，这里打开浏览器就能看见新站点可以运行了
填充内容并修改frontmatter
```
./src/content/docs/blog
```
如果是新建的站，直接在上述目录下写markdown或mdx即可。

新写md的frontmatter要注意:
- 日期date直接按iso格式写，不要加引号
- 页面地址是slug，不是url，不要用/开头和结尾
- 封面用cover，和hugo一些主题的feature一样
- 标签tags和hugo是一样的
- 文件的引用包括图片，astro要用./astro-logo-dark.png
如果是迁移的站，把原来的markdown文件丢到blog目录下，然后自行修订上述内容以符合格式。文章多的话，写几个脚本来改，比改插件代码逻辑要快和简单。用ai生成即可，太过简陋这里就不一一贴出来了。
修改基本设置
```
./astro.config.mjs
```
恢复原有url(permlink)

在astro中，可以在frontmatter中使用slug，和hugo的url效果相同。

这时候问题来了，因为starlight-blog是一个插件，代码中设置了需要prefix开头才可以识别为blog页面或blog文章页面，我的url大部分都是传统wordpress格式的，比如2004/04/25/why-i-blogging，不符合这个插件的识别规则，直接按文档(docs)渲染，等于跳转到另一个页面了。
未完待续