从 Typecho 迁移到 blog-v3：把动态博客变成静态站

这篇记录不是一份“从零开始”的教程，而是一次迁移复盘：为什么从 Typecho 换到 blog-v3，迁移时处理了哪些内容，哪些地方容易踩坑，以及最后如何部署到 Vercel。

blog-v3

基于 Nuxt Content 的静态博客项目

Vercel

用于部署静态站点和前端项目

Nuxt Content Markdown

MDC 语法和 Markdown 内容能力

为什么迁移

Typecho 很轻，写作体验也稳定。它的问题不在“不能用”，而在维护成本会慢慢变成隐形负担：服务器环境、PHP 版本、数据库备份、主题兼容、插件更新、反垃圾评论、附件路径，这些东西都需要持续照看。

我后来更想要的是一种简单的发布链路：

• 文章就是 Markdown 文件。
• 历史版本交给 Git 管。
• 构建和部署交给 Vercel。
• 博客本身尽量不依赖数据库。
• 换服务器、换域名、回滚文章都更直接。

迁移路线

备份 Typecho 数据库和附件

先保留完整数据库、usr/uploads 附件目录、主题目录和配置文件。

导出文章

从数据库中取出文章标题、正文、发布时间、分类、标签、slug 和永久链接。

转换 Markdown

把 Typecho 的 HTML 或 Markdown 内容整理成 blog-v3 能读取的 Markdown 文件。

整理图片与链接

统一图片目录，处理旧站内链、附件路径、相对路径和历史永久链接。

本地构建

在本地运行安装、开发和构建命令，确认文章、组件、RSS、站点地图都能正常生成。

推送 GitHub

把 blog-v3 项目推送到 GitHub，让 Vercel 接管部署流程。

部署到 Vercel

导入仓库，设置构建命令、环境变量和域名，等构建通过后再切换正式流量。

Typecho 和 blog-v3 的差异

备份旧站

迁移第一步不是导出，而是备份。即使后面转换脚本写错、图片路径处理错、文章格式乱掉，只要备份完整，就还能重来。

# 备份数据库
mysqldump -u typecho_user -p typecho_db > typecho-2026-05-04.sql

# 备份附件
tar -czf typecho-uploads-2026-05-04.tar.gz /path/to/typecho/usr/uploads

# 备份主题和配置
tar -czf typecho-site-2026-05-04.tar.gz /path/to/typecho/usr/themes /path/to/typecho/config.inc.php

导出文章

Typecho 的文章主要在 typecho_contents 表里，分类和标签关系通常在 typecho_relationships、typecho_metas 里。我的处理方式是先导出结构化数据，再生成 Markdown 文件。

SELECT
  cid,
  title,
  slug,
  text,
  created,
  modified,
  type,
  status
FROM typecho_contents
WHERE type = 'post'
  AND status = 'publish'
ORDER BY created ASC;

---
title: 文章标题
description: 文章摘要
date: 2026-05-04
updated: 2026-05-04
type: tech
tags: [旧标签一, 旧标签二]
---

这里最耗时间的不是导出，而是清理正文。老文章里可能混着 HTML、短代码、相对图片、旧主题样式类名，以及一些只在 Typecho 插件里有效的写法。

内容清理

我把内容清理拆成三类。

迁移时我保留了一个原则：文章正文尽量变成“普通 Markdown”。只有确实能增强阅读体验的地方，才使用 blog-v3 的 MDC 组件。

比如提示类内容可以改成：

::alert{type="info" title="迁移提示"}
如果旧站文章 URL 已经被搜索引擎收录，迁移后要么保持路径一致，要么配置 301 跳转。
::

配置 blog-v3

blog-v3 本身是 Nuxt 项目。迁移文章之后，重点检查站点信息、导航、评论、站点地图、RSS 和代码高亮配置。

export default {
  site: {
    name: '你的博客名',
    url: 'https://your-domain.example',
    description: '这里写博客描述'
  },
  author: {
    name: '你的名字',
    email: 'you@example.com'
  }
}

本地检查时，我习惯先跑一遍安装和构建。

pnpm i
pnpm init-project
pnpm generate

写文章时常用的快捷键还是那几个：:key{code="Control" icon} + S 保存，:key{code="Control" icon} + K 搜索文件，构建失败就先看终端输出。

部署到 Vercel

Vercel 部署这一步比较直接：

1. 把 blog-v3 项目推送到 GitHub。
2. 在 Vercel 导入这个仓库。
3. Framework Preset 选择 Nuxt。
4. Build Command 使用项目默认构建命令。
5. 确认 Node.js 版本和环境变量。
6. 构建通过后绑定域名。

git add .
git commit -m "migrate blog from typecho to blog-v3"
git push origin main

评论系统怎么处理

Typecho 的评论在数据库里，静态博客没有内置数据库，所以评论迁移要单独考虑。

我没有把评论迁移当成第一优先级。原因很简单：文章内容、链接和图片才是博客迁移的主体。评论可以后处理，甚至可以只保留旧站备份，不导入新系统。

可选方案大概有三种：

永久链接和 SEO

如果旧 Typecho 的 URL 已经被搜索引擎收录，迁移时要特别小心。最理想的情况是新站保持旧路径不变；如果做不到，就配置跳转。

Vercel 可以通过 vercel.json 配置重定向。具体规则要看旧站路径，这里只放一个示例。

{
  "redirects": [
    {
      "source": "/archives/:slug",
      "destination": "/posts/:slug",
      "permanent": true
    }
  ]
}

我的迁移检查清单

迁移后的感受

迁移之后，写作流程变得更“工程化”：新建 Markdown、写 front matter、提交 Git、等待 Vercel 构建。它不一定适合所有人，但很适合希望长期掌控内容、减少服务器维护、让博客更容易迁移和回滚的人。

最后留下一个经验：迁移博客不要追求一次性完美。先让文章、图片、链接和部署跑通，再慢慢处理评论、样式、历史短代码和旧文章修订。静态博客最大的好处，就是每一次调整都能被 Git 记录下来，也都能随时回退。