TYPO3迁移检查清单：开发者分步指南
我经历过足够多的TYPO3迁移，知道流畅过渡和六个月噩梦之间的区别归结为准备工作。TYPO3是一个强大的CMS——自1998年以来就一直存在，运行着一些非常复杂的企业网站，特别是在DACH地区。但当需要迁移时，无论您是在主要TYPO3版本之间升级还是迁移到完全不同的平台，如果您没有计划，这个过程很快就会变成噩梦。
这是我希望在第一次TYPO3迁移之前有人交给我的清单。这不是理论。这里的每一项都存在，因为我见过跳过它会发生什么。
目录
评估您当前的TYPO3安装
在您触碰任何东西之前，您需要确切地理解您在处理什么。这听起来很明显。但事实并非如此。我遇到过的项目中，团队甚至不知道生产环境中运行的是哪个TYPO3版本。
版本和环境审计
从这里开始：
# 检查您的TYPO3版本
php typo3/sysext/core/bin/typo3 --version
# 或通过后端检查：帮助 > 关于 TYPO3
记录以下内容：
- TYPO3版本（主版本和次版本——例如TYPO3 v11.5.38 LTS）
- 运行在服务器上的PHP版本
- 数据库类型和版本（MySQL、MariaDB、PostgreSQL）
- Web服务器（Apache、Nginx）
- 基于Composer的或经典安装——这很重要
- 安装中的网站/域数量（多站点设置增加复杂性）
- 页面树中的总页数和内容元素数
用户和权限映射
TYPO3的后端用户和组权限系统以其细粒度而闻名。导出您的be_users和be_groups表并记录：
- 存在多少个后端用户
- 配置了哪些自定义权限
- 哪些用户拥有管理员访问权限
- 任何自定义TSconfig覆盖
如果您迁移到不同的CMS，您需要将这些角色映射到新系统的权限模型。如果您升级TYPO3版本，某些权限配置可能需要更新。
TypoScript和配置复杂性
运行一个快速的TypoScript设置审计：
# 计算您的TypoScript文件数量
find . -name '*.typoscript' -o -name '*.ts' | wc -l
# 检查setup.txt和constants.txt（遗留格式）
find . -name 'setup.txt' -o -name 'constants.txt' | wc -l
如果您有数百个TypoScript文件，具有深层嵌套配置，预计迁移将花费更长时间。我见过有15年演变历史、超过10,000行TypoScript的TYPO3安装。那不是一个周末项目。
定义您的迁移策略
从根本上说，有三种类型的TYPO3迁移，您需要在开始任何其他工作之前决定您在做哪一种。
| 迁移类型 | 何时选择 | 复杂性 | 典型时间表 |
|---|---|---|---|
| TYPO3版本升级（例如v10 → v12） | 您想保持在TYPO3上 | 中-高 | 4-12周 |
| TYPO3到无头CMS（例如Contentful、Strapi、Sanity） | 您想要现代前端灵活性 | 高 | 8-20周 |
| TYPO3到其他传统CMS（例如WordPress、Drupal） | 您想要不同的整体CMS | 中 | 6-16周 |
| TYPO3到无头TYPO3（使用EXT:headless） | 您想要TYPO3后端和现代前端 | 中 | 6-14周 |
TYPO3内升级
如果您保持在TYPO3上，官方升级路径需要逐步通过每个LTS版本。您不能直接从v8跳到v12。好吧，您可以尝试。不要。
截至2025年推荐的路径：
- v8 LTS → v9 LTS → v10 LTS → v11 LTS → v12 LTS → v13 LTS
TYPO3 v13 LTS在2024年年底发布，是当前的长期支持版本。TYPO3 v12 LTS将通过扩展长期支持（ELTS）计划继续接收安全更新，直到2026年4月。
从TYPO3迁移
如果您要转向无头架构——坦白地说，对许多团队来说这很有意义——您需要评估您的前端框架选项。我们已经对Next.js和Astro作为与无头CMS平台配对的前端层进行了广泛的工作。
关键问题是：您的内容模型是否证明了TYPO3的复杂性？如果您运行的是有200个页面的营销网站，TYPO3可能过度设计了。如果您运行的是具有复杂工作流的多语言企业门户，无论您要去哪里，迁移期间的内容建模工作都将非常重要。
内容审计和数据映射
这是决定迁移成败的地方。内容。
数据库导出和分析
TYPO3主要在这些表中存储内容：
pages——页面树结构tt_content——内容元素sys_file和sys_file_reference——媒体资产（FAL）sys_category——类别tx_news_domain_model_news——如果您使用新闻扩展
导出您的内容并获取实际数字：
-- 按类型统计页面
SELECT doktype, COUNT(*) as count
FROM pages
WHERE deleted = 0
GROUP BY doktype;
-- 按类型统计内容元素
SELECT CType, COUNT(*) as count
FROM tt_content
WHERE deleted = 0 AND hidden = 0
GROUP BY CType
ORDER BY count DESC;
-- 统计文件引用
SELECT COUNT(*) FROM sys_file WHERE missing = 0;
内容类型映射
创建一个电子表格，将每个TYPO3内容类型（CType）映射到目标系统中的等效项。您会遇到的常见TYPO3内容类型：
text、textmedia、textpic——标准文本内容image——图像库table——数据表bullets——列表uploads——文件列表html——原始HTML（这些在迁移期间总是很有趣）list——插件内容（这是变得复杂的地方）- 来自扩展的自定义内容类型
list CType是棘手的。它代表插件内容——新闻列表、表单、自定义功能——每一个都需要单独注意。
多语言内容
TYPO3通过连接模式（其中翻译链接到默认语言记录）或自由模式处理翻译。检查您的网站使用哪种方式：
-- 检查翻译设置
SELECT sys_language_uid, COUNT(*)
FROM pages
WHERE deleted = 0
GROUP BY sys_language_uid;
如果您有8种语言和连接模式翻译，您的迁移数据映射的复杂性增加了8倍。相应地进行计划。
技术基础设施准备
服务器要求
如果您升级到TYPO3 v13，以下是2025年的最低要求：
- PHP 8.2或更高版本（8.3推荐）
- MySQL 8.0+或MariaDB 10.4+或PostgreSQL 12+
- PHP内存限制最少256MB（推荐512MB）
- Composer 2.7+
暂存环境
永远不要——我无法足够强调这一点——永远不要在生产环境中直接运行迁移。设置：
- 镜像生产的暂存环境
- 一个单独的数据库副本
- 相同的PHP和服务器配置
- 文件存储访问（或文件副本）
# 将您的数据库克隆到暂存
mysqldump -u root -p production_db | mysql -u root -p staging_db
# Rsync fileadmin
rsync -avz production:/var/www/html/fileadmin/ staging:/var/www/html/fileadmin/
备份策略
在任何迁移工作开始之前：
- 带时间戳的完整数据库转储
- 包括fileadmin、typo3conf和任何自定义扩展目录的完整文件系统备份
- 记录您的LocalConfiguration.php和AdditionalConfiguration.php设置
- 导出您的TypoScript模板
将这些备份存储在完全独立于迁移环境的地方。我至少保留三份副本。
扩展和集成清单
TYPO3扩展可能是迁移中最大的头痛来源。以下是处理它们的方法。
列出所有已安装的扩展
# 基于Composer的安装
composer show | grep typo3
# 或检查PackageStates.php
cat typo3conf/PackageStates.php
对每个扩展进行分类
对于每个扩展，确定：
| 类别 | 需要的操作 | 示例 |
|---|---|---|
| 核心系统扩展 | 通常由升级向导处理 | fluid_styled_content、form |
| 维护的TER扩展 | 检查与目标版本的兼容性 | news、powermail、solr |
| 已放弃的TER扩展 | 找到替代品或自定义解决方案 | 各种 |
| 自定义网站扩展 | 需要手动迁移/重写 | 您的site_package |
| 商业扩展 | 联系供应商了解迁移路径 | in2publish、各种 |
常见的扩展迁移路径
我在几乎所有TYPO3迁移中看到的一些扩展：
- EXT:news（Georg Ringer）——检查版本兼容性；v11+适用于TYPO3 v12/v13
- EXT:powermail ——流行的表单扩展；替代品包括EXT:form（核心）
- EXT:realurl ——自TYPO3 v9起已弃用；被核心路由替代
- EXT:tt_address ——通常是直接升级
- EXT:gridelements或EXT:flux ——这些布局扩展在升级期间会导致最大的痛苦。如果您迁移离开TYPO3，预计从网格结构中提取内容需要大量工作。
SEO保留计划
跳过本节已经让公司损失了数百万有机流量。不要成为那个团队。
URL映射
- 使用Screaming Frog、Sitebulk或Ahrefs抓取您的整个当前网站
- 导出所有URL（预计大型TYPO3网站有数千个）
- 创建完整的1:1 URL映射文档
- 按有机流量确定您的前100页（检查Google搜索控制台）
- 优先考虑高流量页面的重定向准确性
重定向实现
# 示例 .htaccess重定向
RedirectPermanent /old-typo3-path/page.html /new-path/page
RedirectPermanent /index.php?id=123 /about-us
对于大规模重定向，使用重定向管理解决方案，而不是将数千条规则填充到.htaccess中。如果您要转向现代堆栈，大多数框架和托管平台（Vercel、Netlify）都有重定向配置文件。
元数据迁移
TYPO3在pages表中存储SEO元数据（自EXT:seo在v9中成为核心扩展以来）：
seo_titleog_title、og_description、og_imagetwitter_title、twitter_description、twitter_imagecanonical_linkno_index、no_follow
确保您导出并映射所有这些。丢失500个页面的元描述是可以预防的灾难。
迁移执行阶段
对于TYPO3版本升级
为每个版本步骤遵循此序列：
- 更新Composer依赖到下一个LTS版本
- 运行升级向导在安装工具中（管理工具 > 升级）
- 执行数据库分析器以更新架构
- 检查弃用日志以查找问题
- 更新扩展到兼容版本
- 修复TypoScript弃用和重大变更
- 彻底测试后再进行下一个版本步骤
# 通过Composer更新TYPO3核心
composer require typo3/cms-core:^13.4 typo3/cms-backend:^13.4 \
typo3/cms-frontend:^13.4 --with-all-dependencies
# 通过CLI运行升级向导
php typo3/sysext/core/bin/typo3 upgrade:run
# 数据库架构更新
php typo3/sysext/core/bin/typo3 database:updateschema
对于平台迁移
如果您迁移到无头CMS架构，执行阶段看起来不同：
- 设置新CMS并配置内容模型
- 构建迁移脚本以转换TYPO3数据
- 分批迁移内容——从最简单的内容类型开始
- 处理媒体资产——从fileadmin下载并上传到新资产存储
- 使用您选择的框架构建前端
- 在切换前实现重定向
- DNS切换和监控
对于实际的数据转换，我通常编写从TYPO3数据库读取并通过API推送内容到新CMS的Python或Node.js脚本：
import mysql.connector
import requests
# 连接到TYPO3数据库
db = mysql.connector.connect(
host="localhost",
user="typo3",
password="password",
database="typo3_db"
)
cursor = db.cursor(dictionary=True)
cursor.execute("""
SELECT uid, title, description, slug,
seo_title, og_description
FROM pages
WHERE deleted = 0 AND hidden = 0
AND sys_language_uid = 0
ORDER BY sorting
""")
for page in cursor.fetchall():
# 转换并推送到新CMS
payload = {
"title": page["title"],
"slug": page["slug"],
"seoTitle": page["seo_title"] or page["title"],
"description": page["og_description"] or page["description"]
}
# POST到您的新CMS API
response = requests.post(
"https://api.new-cms.com/content",
json=payload,
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(f"Migrated page {page['uid']}: {response.status_code}")
测试和质量保证
自动化测试清单
- 所有页面返回200状态码
- 没有断开的内部链接
- 所有图像加载正确
- 表单提交成功
- 搜索功能有效
- 多语言切换有效
- 旧URL的重定向有效
- 规范URL正确
- XML站点地图有效且可访问
- robots.txt配置正确
- SSL证书有效
- 页面加载时间可接受（在3秒以下）
视觉回归测试
使用Percy、BackstopJS或Playwright进行视觉比较：
# BackstopJS示例
npx backstop init
# 在backstop.json中配置场景
npx backstop reference # 捕获当前网站
npx backstop test # 在迁移后进行比较
性能基准
测量之前和之后。您的迁移理想情况下应改进性能，而不是降低性能。
| 指标 | 迁移前目标 | 迁移后目标 |
|---|---|---|
| TTFB | < 800ms | < 200ms |
| LCP | < 2.5s | < 1.5s |
| CLS | < 0.1 | < 0.05 |
| FID/INP | < 200ms | < 100ms |
| PageSpeed分数 | 50-70 | 90+ |
如果您从服务器渲染的TYPO3迁移到静态或边缘渲染的前端，您应该会看到这些数字的显著改进。
迁移后监控
迁移在您翻转DNS时未完成。至少监控30天：
- Google搜索控制台——观察抓取错误、覆盖问题和索引问题。预计前两周会有一些波动。
- 分析——将流量模式与迁移前基线进行周对周比较。
- 404错误——为404设置日志记录，并为您遗漏的任何URL添加重定向。
- 核心Web指标——通过CrUX或您的分析平台监控真实用户数据。
- 服务器日志——观察异常错误模式。
为任何之前在前50名中的页面设置流量下降超过20%的警报。
常见TYPO3迁移陷阱
这些是我在数十次迁移中看到的（有时犯过）的错误：
1. 忽视软删除的记录。 TYPO3使用deleted=1标志而不是实际删除记录。您的迁移脚本需要过滤这些，否则您将导入数千条多年前删除的记录。
2. 忘记工作区。 如果网站使用TYPO3工作区进行编辑工作流，您可能在导出中混合了草稿内容。始终过滤t3ver_wsid = 0以仅获取实时内容。
3. 低估RTE内容。 TYPO3的富文本编辑器输出可能包含自定义标签、<link>标签和TYPO3特定语法以及t3:// URI。您需要解析并转换所有这些。
4. 破坏文件引用。 TYPO3的文件抽象层（FAL）使用sys_file_reference连接文件到内容。它不是简单的"内容记录上的图像字段"——它是一个关系表。您的迁移脚本需要跟随这些引用。
5. 未按实际内容量进行测试。 您的迁移脚本对10个测试页面效果很好。它对15,000个页面和50,000个内容元素的规模失败了。始终按规模测试。
如果您计划迁移并想避免这些陷阱，我们已经指导过几个企业团队完成TYPO3迁移——随时联系我们，我们可以讨论您的具体情况。
常见问题
TYPO3迁移通常需要多长时间？ 这主要取决于您安装的复杂性。对于具有标准扩展的单语言网站的直接TYPO3 v11到v13升级可能需要4-6周。多语言企业TYPO3网站的完整平台迁移，具有自定义扩展，可能需要3-6个月。仅内容审计阶段对于大型网站可能需要2-4周。
我可以在升级期间跳过TYPO3 LTS版本吗？ 从技术上讲，您不应该。官方建议是按顺序升级到每个LTS版本（v8 → v9 → v10 → v11 → v12 → v13），因为每个版本都包括处理该特定步骤数据迁移的升级向导。跳过版本意味着这些数据迁移不会运行，您最终会得到损坏或孤立的数据。一些代理声称他们可以进行跳过版本的升级，但我见过它导致几个月后出现的微妙数据问题。
我应该从TYPO3迁移到WordPress吗？ 这取决于您的需求。WordPress能够很好地处理简单的营销网站，但如果您最初选择TYPO3是因为复杂的多语言要求、细粒度权限或企业工作流，WordPress可能是倒退。考虑无头CMS与现代前端框架配对是否可能是更好的选择。我们已经撰写了关于无头CMS开发方法的文章，这些方法通常对离开企业CMS平台的团队更有意义。
在TYPO3迁移期间，我的SEO排名会发生什么？ 预计2-6周的排名波动，即使有完美的重定向。Google需要时间重新抓取和重新索引您的内容。要最小化影响：为每个URL实现301重定向，保持内容结构尽可能接近原始，立即提交更新的站点地图，如果更改域，使用Google搜索控制台中的地址变更工具。处理重定向得当的网站通常在4-8周内恢复。
如何处理目标平台上不存在的TYPO3扩展？ 首先，确定扩展实际做什么。许多TYPO3扩展提供的功能在现代平台中已内置（如表单生成器、SEO工具或重定向管理）。对于自定义功能，您需要找到等效的插件/服务或构建自定义功能。创建一个电子表格，列出每个扩展、其目的和替换策略。
值得迁移到无头TYPO3而不是完全迁移吗？ TYPO3无头扩展（EXT:headless）如果您的团队对TYPO3后端感到舒适但想要现代前端，这是一个合理的选择。它将TYPO3内容作为JSON API公开，让您使用Next.js、Nuxt或Astro构建前端。这种方法保留了现有的内容结构和编辑工作流，同时现代化了呈现层。这是一个很好的折中，尽管这确实意味着您仍在维护TYPO3后端。
2025年TYPO3迁移的成本是多少？ 大概数字：中等规模网站的TYPO3版本升级成本为$15,000-$50,000。完整的平台迁移到无头架构的范围从$40,000-$150,000+，取决于内容量、语言数量、自定义功能和集成复杂性。这些不是小数字，但请将其与维护过期、不安全CMS安装的成本进行比较。您可以查看我们的定价页面以了解我们如何为这些项目定价的更多详情。
我需要从头开始重建我的模板吗？ 对于TYPO3版本升级，通常不完全需要——但您将需要更新Fluid模板以处理已弃用的ViewHelper和新API。对于平台迁移，是的，您在构建新前端。好消息是现代框架如Next.js和Astro使快速构建高性能前端比Fluid/TypoScript时代要快得多。您的设计可以保持相同；实现只是改变。