我已經經歷過足夠多的 TYPO3 遷移，深知成功過渡與六個月的噩夢之間的區別在於準備工作。TYPO3 是一個功能強大的 CMS — 自 1998 年以來就已存在，且運行著一些非常複雜的企業網站，特別是在 DACH 地區。但當需要遷移時，無論你是升級 TYPO3 主要版本還是遷移到完全不同的平台，如果沒有計劃，整個過程會迅速惡化。

這是我希望在第一次 TYPO3 遷移前有人交給我的檢查清單。這不是理論性的。這裡的每一項都存在，因為我見過跳過它會發生什麼。

目錄

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide

評估你的當前 TYPO3 安裝

在你觸及任何東西之前，你需要準確了解你正在使用什麼。這聽起來很明顯。事實並非如此。我曾進過一些項目，團隊甚至不知道他們在生產環境中運行的是哪個 TYPO3 版本。

版本和環境審計

從這裡開始：

# 檢查你的 TYPO3 版本
php typo3/sysext/core/bin/typo3 --version

# 或通過後台檢查：Help > About 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 文件，配置深層嵌套，預計遷移需要更長時間。我見過有 10,000+ 行 TypoScript 的 TYPO3 安裝，這些代碼已經演進了 15 年。這不是一個週末項目。

定義你的遷移策略

根本上有三種類型的 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 Migration Checklist: A Developer's Step-by-Step Guide - architecture

技術基礎架構準備

伺服器要求

如果你升級到 TYPO3 v13，以下是 2025 年的最低要求：

  • PHP 8.2 或更高版本（推薦 8.3）
  • MySQL 8.0+ 或 MariaDB 10.4+ 或 PostgreSQL 12+
  • 256MB PHP 內存限制最小（建議 512MB）
  • Composer 2.7+

測試環境

永遠 — 我無法強調這一點夠充分 — 永遠不要直接在生產上運行遷移。設置：

  1. 鏡像生產的測試環境
  2. 單獨的數據庫副本
  3. 相同的 PHP 和伺服器配置
  4. 文件存儲訪問（或文件副本）
# 將數據庫克隆到測試環境
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 映射

  1. 用 Screaming Frog、Sitebulk 或 Ahrefs 爬取整個當前網站
  2. 導出所有 URL（大型 TYPO3 網站預期數千個）
  3. 創建完整的 1:1 URL 映射文件
  4. 按有機流量識別你的前 100 頁（檢查 Google Search Console）
  5. 優先考慮高流量頁面的重定向準確性

重定向實現

# 示例 .htaccess 重定向
RedirectPermanent /old-typo3-path/page.html /new-path/page
RedirectPermanent /index.php?id=123 /about-us

對於大規模重定向，使用重定向管理解決方案，而不是將數千條規則塞入 .htaccess。如果你移動到現代堆疊，大多數框架和託管平台（Vercel、Netlify）都有重定向配置文件。

元數據遷移

TYPO3 將 SEO 元數據存儲在 pages 表中（自 EXT:seo 在 v9 中成為核心擴展以來）：

  • seo_title
  • og_title、og_description、og_image
  • twitter_title、twitter_description、twitter_image
  • canonical_link
  • no_index、no_follow

確保你導出並映射所有內容。在 500 頁中丟失你的元描述是一場可預防的災難。

遷移執行階段

對於 TYPO3 版本升級

對每個版本步驟遵循此序列：

  1. 更新 Composer 依賴項到下一個 LTS 版本
  2. 運行升級精靈在安裝工具中（Admin Tools > Upgrade）
  3. 執行數據庫分析器以更新架構
  4. 檢查棄用日誌以查找問題
  5. 更新擴展到兼容版本
  6. 修復 TypoScript 棄用和破壞性更改
  7. 徹底測試，然後移動到下一個版本步驟
# 通過 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 架構，執行階段看起來不同：

  1. 設置新 CMS 並配置內容模型
  2. 構建遷移腳本以轉換 TYPO3 數據
  3. 分批遷移內容 — 從最簡單的內容類型開始
  4. 處理媒體資產 — 從 fileadmin 下載並上傳到新資產存儲
  5. 構建前端使用你選擇的框架
  6. 實現重定向在上線前
  7. DNS 切換和監控

對於實際數據轉換，我通常編寫 Python 或 Node.js 腳本，從 TYPO3 數據庫讀取並通過 API 將內容推送到新 CMS：

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 Score 50-70 90+

如果你從伺服器呈現的 TYPO3 遷移到靜態或邊緣呈現的前端，你應該看到這些數字中的巨大改進。

遷移後監控

當你翻轉 DNS 時，遷移並未完成。至少監控 30 天的以下內容：

  1. Google Search Console — 監視爬蟲錯誤、覆蓋問題和索引問題。預期前兩週有一些波動。
  2. 分析 — 將流量模式與遷移前的基準進行周比較。
  3. 404 錯誤 — 為 404 設置日誌記錄，並為你遺漏的任何 URL 添加重定向。
  4. Core Web Vitals — 通過 CrUX 或你的分析平台監控真實用戶數據。
  5. 伺服器日誌 — 監視異常錯誤模式。

為任何以前在前 50 名中的頁面的流量下降超過 20% 設置警報。

常見 TYPO3 遷移陷阱

這些是我在數十次遷移中看到的（有時製造的）錯誤：

1. 忽視軟刪除的記錄。 TYPO3 使用 deleted=1 標誌而不是實際刪除記錄。你的遷移腳本需要過濾這些，否則你會導入數年前刪除的數千條記錄。

2. 忘記工作區。 如果網站使用 TYPO3 工作區進行編輯工作流程，你可能有混合到導出中的草稿內容。始終過濾 t3ver_wsid = 0 以獲得僅實時內容。

3. 低估 RTE 內容。 TYPO3 的富文本編輯器輸出可以包含自定義標籤、具有 TYPO3 特定語法的 <link> 標籤和 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 Search Console 中使用「地址更改」工具。正確處理重定向的網站通常在 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 模板以處理已棄用的 ViewHelpers 和新 API。對於平台遷移，是的，你正在構建一個新前端。好消息是現代框架如 Next.js 和 Astro 使構建高效前端的速度明顯快於 Fluid/TypoScript 時代。你的設計可以保持相同；實現只是改變。