Back to Details

content-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Content Migration

内容迁移

Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic.
在不同平台、域名或URL结构之间迁移内容，同时确保SEO不受影响、用户书签可用且下游集成功能正常。此技能与技术栈无关。

When to use

使用场景

  • Migrating from one CMS to another (e.g., WordPress to a headless setup)
  • Consolidating multiple sites into one
  • Splitting one site into multiple
  • Changing URL structures
  • Domain migration (one brand to another, mergers, rebrands)
  • Migrating from a custom build to a platform (or vice versa)
  • Content audit-driven cleanup as part of a larger move
  • 从一款CMS迁移至另一款（例如：从WordPress迁移至无头架构）
  • 将多个网站合并为一个
  • 将单个网站拆分为多个
  • 变更URL结构
  • 域名迁移（品牌更换、企业合并、品牌重塑）
  • 从自定义构建系统迁移至平台（反之亦然）
  • 作为大型迁移项目的一部分，基于内容审核进行清理

When NOT to use

非适用场景

  • A net-new site with no existing content (no migration needed)
  • Single-page edits or content updates within an existing site (use 
    content-and-copy
    )
  • Performance or technical SEO improvements without URL changes (use 
    seo-technical
    )
  • Routine content audits (use 
    seo-content-audit
    )
  • 无现有内容的全新网站（无需迁移）
  • 现有网站内的单页编辑或内容更新（使用
    content-and-copy
    技能）
  • 不涉及URL变更的性能优化或技术SEO改进（使用
    seo-technical
    技能）
  • 常规内容审核（使用
    seo-content-audit
    技能）

Required inputs

必要输入

  • The source: current platform, current URL structure, current content inventory
  • The destination: target platform, target URL structure, target capabilities
  • The reason for migration (drives priority of what to preserve)
  • Constraints (timeline, budget, downtime tolerance)
  • Stakeholders (SEO, content, dev, comms, support)
  • 源信息：当前平台、当前URL结构、当前内容清单
  • 目标信息：目标平台、目标URL结构、目标平台能力
  • 迁移原因（决定需优先保留的内容）
  • 约束条件（时间线、预算、停机容忍度）
  • 相关利益方（SEO团队、内容团队、开发团队、传播团队、支持团队）

The framework: 6 phases

框架：6个阶段

Every content migration follows the same arc. Skipping a phase is how migrations go badly.
所有内容迁移都遵循相同的流程。跳过任何一个阶段都可能导致迁移失败。

Phase 1: Inventory

阶段1：内容清单梳理

You can't migrate what you don't know. Build a complete map of what exists.
For each piece of content:
  • URL
  • Title
  • Content type (article, landing page, product, doc, etc.)
  • Status (live, draft, archived, scheduled)
  • Last modified
  • Author or owner
  • Traffic (last 12 months)
  • Backlinks (top external referrers)
  • Internal links pointing to it
  • Embedded assets (images, video, downloads)
Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool.
The inventory is a spreadsheet. It's the source of truth for the rest of the migration.
您无法迁移未知的内容。需构建一份完整的现有内容映射表。
针对每一项内容，需记录：
  • URL
  • 标题
  • 内容类型（文章、着陆页、产品页、文档等）
  • 状态（已上线、草稿、已归档、已排期）
  • 最后修改时间
  • 作者或负责人
  • 流量数据（过去12个月）
  • 反向链接（主要外部引荐来源）
  • 指向该内容的内部链接
  • 嵌入资源（图片、视频、下载文件）
数据来源：CMS导出文件、XML站点地图、服务器日志、分析工具、搜索控制台、反向链接工具。
内容清单以电子表格形式呈现，是整个迁移过程的唯一可信来源。

Phase 2: Audit and decide

阶段2：审核与决策

For each piece of content, decide:
  • Keep: migrate as-is
  • Update: migrate with edits (refresh, expand, fix)
  • Merge: combine with another piece, redirect both old URLs to the new
  • Redirect: don't migrate; redirect to a related page
  • Delete: don't migrate, no redirect (use sparingly; only for clearly low-value pages)
This is 
seo-content-audit
work. The migration is the time to do it; not the time to skip it.
For each "Update" or "Merge," document the specific changes.
针对每一项内容，做出以下决策：
  • 保留：原样迁移
  • 更新：迁移时进行编辑（刷新、扩展、修复）
  • 合并：与另一项内容合并，将两个旧URL重定向至新URL
  • 重定向：不迁移，重定向至相关页面
  • 删除：不迁移，也不设置重定向（谨慎使用；仅适用于明显低价值的页面）
这属于
seo-content-audit
技能的工作范畴。迁移期间是完成此项工作的最佳时机，切勿跳过。
对于每一项标记为"更新"或"合并"的内容，需记录具体的变更内容。

Phase 3: Map URLs

阶段3：URL映射

The URL map is the most important migration artifact.
Old URLNew URLStatus codeReason
/old/path/new/path301Direct equivalent
/old/page-1, /old/page-2/new/merged301Merged content
/old/deprecated/related/replacement301Closest replacement
/old/junk(none)410Intentionally gone
Rules:
  • 301 (permanent redirect) for content that has a new home
  • 410 (gone) for intentionally deleted content
  • Avoid 404 (not found) where 410 is more accurate
  • Never redirect everything to the homepage; specific is always better
  • Map every URL with traffic or backlinks; lower-priority URLs can be patterned
For domain migrations, use a 1:1 path mapping by default (
old.com/page
→ 
new.com/page
) with specific overrides where structure changes.
URL映射表是迁移过程中最重要的文件。
旧URL新URL状态码原因
/old/path/new/path301直接对应
/old/page-1, /old/page-2/new/merged301内容合并
/old/deprecated/related/replacement301最接近的替代页面
/old/junk(无)410主动删除
规则：
  • 为有新归属的内容使用301（永久重定向）
  • 为主动删除的内容使用410（已删除）
  • 若410更准确，避免使用404（未找到）
  • 切勿将所有内容重定向至首页；具体映射始终更优
  • 为所有有流量或反向链接的URL建立映射；低优先级URL可采用模式化映射
对于域名迁移，默认使用1:1路径映射（
old.com/page
→ 
new.com/page
），仅在结构变更时进行特定覆盖。

Phase 4: Build and stage

阶段4：构建与 staging 环境部署

Build the destination. Don't skip a staging environment.
  • Set up the new platform with the new content
  • Implement the URL map (most platforms support a redirect file or rule)
  • Verify a representative sample of redirects work
  • Test critical user flows (signup, purchase, contact)
  • Validate analytics, monitoring, and integrations
  • Test from search engine perspective: robots.txt, sitemap, canonicals
If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip.
搭建目标平台。切勿跳过staging环境。
  • 在新平台上部署新内容
  • 实施URL映射表（大多数平台支持重定向文件或规则）
  • 验证代表性样本的重定向是否正常工作
  • 测试关键用户流程（注册、购买、联系）
  • 验证分析工具、监控工具和集成功能
  • 从搜索引擎视角测试：robots.txt、站点地图、规范标签
若可能，在切换前让Google抓取目标平台，以便重定向生效时内容已被收录。

Phase 5: Cut over

阶段5：切换上线

The actual switch. Plan it like a launch (and use 
launch-runbook
alongside this skill).
Pre-cutover:
  • Comms to stakeholders (date, expected impact)
  • Comms to users if downtime expected
  • Support team prepped for likely questions
  • Lower DNS TTL the day before (1-3 days for safety)
  • Backup of source platform (in case rollback is needed)
Cutover:
  • Redirect rules go live
  • DNS changes go live
  • New sitemap submitted to search engines
  • Old sitemap removed or updated
  • Internal links audited and updated to point to new URLs (where possible)
  • Status page or banner if user-visible disruption
Immediately post-cutover:
  • Smoke test top 50 pages from the inventory
  • Verify redirects are 301 (not 302)
  • Verify search console for errors
  • Watch real-time traffic for unexpected drops
  • Watch error logs for missing assets, broken integrations
实际切换过程。需像网站上线一样规划（同时搭配
launch-runbook
技能使用）。
切换前：
  • 向利益方传达信息（日期、预期影响）
  • 若预计停机，向用户发布通知
  • 支持团队准备好应对常见问题
  • 提前一天降低DNS TTL（设置为1-3天以确保安全）
  • 备份源平台内容（以便需要回滚）
切换中：
  • 重定向规则生效
  • DNS变更生效
  • 向搜索引擎提交新的站点地图
  • 删除或更新旧站点地图
  • 审核并更新内部链接，使其指向新URL（如有可能）
  • 若用户可见中断，设置状态页面或横幅通知
切换后立即：
  • 对内容清单中排名前50的页面进行冒烟测试
  • 验证重定向为301而非302
  • 检查搜索控制台是否有错误
  • 监控实时流量是否出现意外下降
  • 查看错误日志是否有缺失资源、集成功能损坏等问题

Phase 6: Monitor and recover

阶段6：监控与恢复

The migration isn't done at cutover. The next 30-90 days reveal problems.
Watch:
  • Traffic: expect a temporary drop (10-30% is common); should recover in 4-8 weeks. A persistent drop beyond that is a problem.
  • Indexing: new URLs should be crawled and indexed. Check coverage in search console.
  • Rankings: track top keywords. A position drop is normal; a position cliff is a sign of a redirect or canonical problem.
  • Backlinks: check that linked-from-elsewhere pages still resolve to the right destination.
  • 404s: any URL getting 404s that should have been redirected? Add to the map.
  • User reports: support tickets, social media. Are users finding their old links?
Common 30-day fixes:
  • Add missed redirects from 404 patterns
  • Update internal links you missed
  • Re-submit sitemap if indexing stalls
  • Investigate and fix any crawl errors
迁移工作并非在切换上线后就结束。接下来的30-90天内会暴露问题。
需监控：
  • 流量：预计会出现临时下降（10-30%为正常情况）；应在4-8周内恢复。若持续下降则表明存在问题。
  • 收录情况：新URL应被抓取并收录。检查搜索控制台的覆盖范围。
  • 排名：跟踪核心关键词。排名下降属于正常情况；若排名暴跌则表明重定向或规范标签存在问题。
  • 反向链接：检查外部链接指向的页面是否仍能正确跳转至目标地址。
  • 404错误：是否存在应设置重定向但返回404的URL？将其添加至映射表。
  • 用户反馈：支持工单、社交媒体。用户能否找到旧链接？
常见的30天内修复措施：
  • 为404错误模式添加遗漏的重定向
  • 更新遗漏的内部链接
  • 若收录停滞，重新提交站点地图
  • 调查并修复任何抓取错误

Workflow

工作流程

Step 1: Set the scope

步骤1：确定范围

What's in scope? What's out? Write it down. Migrations expand if not bounded.
哪些内容在迁移范围内？哪些不在？记录下来。若不加以限制，迁移范围会不断扩大。

Step 2: Build the inventory

步骤2：构建内容清单

Pull every URL, traffic, backlinks, internal links. The spreadsheet is the artifact.
收集所有URL、流量数据、反向链接、内部链接。电子表格是最终产出物。

Step 3: Decide per piece

步骤3：逐项决策

Keep, update, merge, redirect, delete. Document decisions.
保留、更新、合并、重定向、删除。记录决策内容。

Step 4: Map URLs

步骤4：URL映射

The complete redirect map. Reviewed by SEO and content stakeholders.
完成完整的重定向映射表。需经SEO和内容利益方审核。

Step 5: Build the destination

步骤5：搭建目标平台

In a staging environment. Real content (or representative content). Real redirects.
在staging环境中搭建。使用真实内容（或代表性内容）和真实重定向规则。

Step 6: Test

步骤6：测试

  • Sample of redirects (top 20 by traffic, top 20 by backlinks, edge cases)
  • Critical flows (signup, checkout, contact)
  • Analytics and monitoring
  • Search-engine perspective (robots.txt, sitemap, canonicals)
  • 重定向样本（流量排名前20、反向链接排名前20、边缘案例）
  • 关键流程（注册、结账、联系）
  • 分析工具与监控工具
  • 搜索引擎视角（robots.txt、站点地图、规范标签）

Step 7: Cut over

步骤7：切换上线

Following the cutover checklist. Have rollback ready.
遵循切换上线检查清单。准备好回滚方案。

Step 8: Monitor

步骤8：监控

Daily for the first week. Weekly for the first month. Monthly through 90 days.
第一周每日监控，第一个月每周监控，90天内每月监控。

Step 9: Document the result

步骤9：记录结果

What worked. What didn't. Lessons. (See 
after-action-report
.)
哪些措施有效？哪些无效？经验教训。（参考
after-action-report
技能）

Failure patterns

失败模式

No URL inventory. Migration team thinks they have everything. They don't. Old PDFs, archived posts, marketing landing pages with backlinks. Build the inventory.
302 redirects instead of 301. 302 is temporary. SEO equity doesn't reliably pass. Use 301 unless you have a specific reason.
Redirecting everything to the homepage. "We'll let users find their way." They won't. They'll bounce. Map specifically.
Long redirect chains. /a → /b → /c → /d. Each hop loses a little equity and adds latency. Collapse to /a → /d.
Forgetting non-HTML URLs. PDFs, images, downloads. They have URLs too. They have backlinks too. Include in the map.
Forgetting query strings. 
/page?id=123
is a different URL than 
/page
. Patterns or specific maps for query string variants.
Ignoring trailing slashes. 
/page
and 
/page/
are different to most servers. Pick one canonical form. Redirect the other.
No staging. The first time the migration runs is in production. Things break. Stage and test.
Stage that's too different from production. Different DNS, different CDN, different platform. Tests pass on staging, fail on production. Stage as close to prod as feasible.
Leaving the source live. Two sites serving the same content. Duplicate content, split equity, user confusion. Take down the source after confirming the destination is solid.
Leaving the source domain unrenewed. Domain expires, redirects break, traffic dies. Renew the source domain for a long time, even if you're not using it.
Big-bang migration with no rollback plan. Something goes wrong. Now what? Plan rollback before cutover.
Cutover during a busy period. End of quarter, holiday season, big campaign. Bad timing. Pick a quiet period.
No comms. Users find their bookmarks broken with no warning. Some won't come back. Communicate.
Migration as a one-time event. It's not done at cutover. Monitor for 30-90 days. Fix what surfaces.
Treating migration as just a dev project. SEO, content, support, comms all need to be involved. Cross-functional from day one.
无URL清单：迁移团队认为已掌握所有内容，但实际并非如此。旧PDF文件、归档文章、带有反向链接的营销着陆页都可能被遗漏。务必构建内容清单。
使用302重定向而非301：302是临时重定向，无法可靠传递SEO权益。除非有特殊原因，否则使用301。
将所有内容重定向至首页："让用户自行查找内容"。用户不会这么做，他们会直接离开。需进行具体映射。
过长的重定向链：/a → /b → /c → /d。每一次跳转都会损失部分SEO权益并增加延迟。应简化为/a → /d。
忽略非HTML URL：PDF、图片、下载文件也有URL，且可能带有反向链接。需将其纳入映射表。
忽略查询字符串：
/page?id=123
与
/page
是不同的URL。需为查询字符串变体制定模式或具体映射。
忽略尾部斜杠：大多数服务器会将
/page
和
/page/
视为不同URL。选择一种规范形式，将另一种重定向至该形式。
无staging环境：首次迁移就在生产环境中进行，导致问题频发。务必搭建staging环境并进行测试。
staging环境与生产环境差异过大：DNS、CDN、平台不同。staging环境测试通过，但生产环境失败。staging环境应尽可能接近生产环境。
源平台仍保持上线状态：两个网站提供相同内容，导致重复内容、SEO权益分散、用户混淆。确认目标平台稳定后，关闭源平台。
未续费源域名：域名过期，重定向失效，流量骤降。即使不使用源域名，也需长期续费。
无回滚计划的大规模迁移：出现问题时束手无策。切换上线前需制定回滚计划。
在繁忙时段切换上线：季度末、节假日、大型活动期间。时机不佳。应选择低峰时段。
无沟通：用户发现书签失效却未收到任何通知。部分用户可能不会再返回。务必提前沟通。
将迁移视为一次性事件：切换上线并不意味着迁移完成。需监控30-90天，修复出现的问题。
将迁移仅视为开发项目：SEO、内容、支持、传播团队都需参与。从第一天起就应跨职能协作。

Output format

输出格式

A migration plan document includes:
  • Scope: what's in, what's out
  • Inventory: the URL spreadsheet
  • Audit decisions: keep, update, merge, redirect, delete
  • URL map: old to new, with status codes
  • Architecture: new platform setup, redirect implementation
  • Cutover plan: the runbook for switch day
  • Rollback plan: if it goes wrong
  • Monitoring plan: what's watched, for how long
  • Comms plan: internal and external
  • Owners and timeline: who does what when
迁移计划文档应包含：
  • 范围：包含与排除的内容
  • 内容清单：URL电子表格
  • 审核决策：保留、更新、合并、重定向、删除的决策记录
  • URL映射表：旧URL到新URL的映射及状态码
  • 架构：新平台设置、重定向实现方式
  • 切换上线计划：切换当日的执行手册
  • 回滚计划：出现问题时的应对方案
  • 监控计划：监控内容与时长
  • 沟通计划：内部与外部沟通方案
  • 负责人与时间线：各任务的负责人与时间节点

Reference files

参考文件

  • references/migration-runbook.md
    : Step-by-step runbook for cutover day, including pre-flight checks, the actual switch, immediate verification, and the first 24 hours of monitoring.
  • references/migration-runbook.md
    ：切换当日的分步执行手册，包括飞行前检查、实际切换、立即验证及切换后24小时监控。