Confluence 迁移后出现链接打不开，通常集中在页面 ID 与空间键变化、附件路径重写、外部系统保存的旧绝对地址，以及别名和重定向未同步这几类原因。处理时先按链接类型统计失效范围，再抽样确认原因，然后分类型修复并建立旧地址到新地址的跳转，最后用回归验证确认恢复。本文按这条路径展开，适合正在处理迁移后链接问题的团队参考。
要点总览（TL;DR）
- 先按链接类型和失效表现统计范围，区分本次迁移引起与迁移前已存在的失效链接，避免全量重写放大风险。
- 对每类失效建立原因假设并用抽样比对、重定向检查、多角色访问等证据确认，再进入处置。
- 处置以旧新地址映射表为基础：站内互链批量替换前备份，外部深链以重定向承接，权限问题单独恢复。
- 修复后按类型抽样回归并做全量扫描，把链接校验纳入迁移验收清单，明确负责人和检查时点。
先分清失效的是哪几类链接
“链接失效”是一个笼统说法，不同链接的失效机制和修复方式差别很大。直接全量重写会把本来正常的链接一起改坏，也会掩盖真正的权限或路径问题。第一步是把问题拆成可分别处置的类别，形成一份带范围的失效清单。
按链接类型分类
- 页面互链：Confluence 页面正文中指向其他页面的链接，通常带页面 ID 或空间键。
- 空间首页与导航：空间入口、侧边栏导航、面包屑中配置的地址。
- 附件与图片：正文中嵌入的附件下载地址和图片引用路径。
- 外部系统保存的深链：工单系统、IM 消息、邮件模板、内部门户中保存的 Confluence 绝对地址。
- 书签与邮件里的旧地址：用户浏览器书签、历史邮件中散落的链接，无法集中修改，只能靠重定向承接。
按表现分类
同样是“打不开”，表现不同，指向的原因也不同。404 通常意味着地址无法解析，可能是 ID 或路径变化；跳转到错误页面说明地址能解析但映射错了对象；图片附件缺失多为引用路径未同步；登录后仍打不开则要优先怀疑权限设置。把表现记录下来，后续验证原因时可以直接对照。
统计口径与范围界定
建议按统一口径统计：失效链接数量、涉及哪些空间、集中出现的时间点和迁移批次。集中出现在某次迁移之后，说明与那次迁移动作相关；分散在多个批次、时间跨度很长，则可能包含迁移前就已存在的失效链接。区分这两类很重要，迁移前已失效的链接不应计入本次迁移的问题范围，否则会高估影响面，也会让修复工作量失真。
完成这一步的交付物是一份失效链接清单：每条记录链接类型、所在位置、失效表现、发现时间和所属迁移批次，并标注是否确认由本次迁移引起。
逐类验证原因，区分假设与证据
分类完成后，容易犯的错误是看到 404 就断定是 ID 变化，然后直接开始批量替换。原因判断需要证据支撑，下面按类型列出常见原因假设和对应的验证方法，确认后再进入处置。
| 失效类型 | 原因假设 | 验证方法 |
|---|---|---|
| 页面互链 404 | 页面 ID 或空间键在迁移中变化，旧 URL 无法解析 | 抽样打开失效链接，记录旧 URL；在新站找到对应页面，比对两者的 ID 与空间键差异 |
| 图片、附件缺失 | 附件与图片存储路径被重写，正文引用地址未同步更新 | 打开页面编辑态查看引用地址，与附件实际存放路径比对；抽查若干页面确认是否普遍存在 |
| 外部系统深链打不开 | 外部系统保存的是旧域名或旧绝对地址 | 在外部系统中找到配置项，确认地址指向旧域名；用新地址手工替换后测试是否可达 |
| 链接可解析但打不开 | 权限或匿名访问设置变化 | 用页面管理员、普通成员、未登录三种身份分别访问同一链接，对比结果 |
| 旧短链、别名失效 | 别名与重定向未随迁移一并建立 | 检查新站是否配置了对应的重定向规则；访问旧短链观察返回状态 |
验证时注意两点。其一，抽样要覆盖不同空间和不同迁移批次，单一空间的样本不足以代表整体。其二，同一批失效链接可能由多个原因叠加，例如页面 ID 变化的同时权限也收紧了，只验证一层会得出错误结论。对每条原因假设，记录验证所用的链接样本、比对结果和结论，形成“假设—证据—结论”的对照记录，后续处置时按结论执行，避免反复猜测。
如果验证后发现某类链接的失效比例很低且原因不明，先标记为待观察，不要为了追求全部修复而对其做批量操作。范围不清的批量改写风险高于收益。
按类型处置：修复、重定向与批量替换
原因确认后进入处置。核心原则是先建立旧地址到新地址的映射表，再决定用重定向承接还是直接改写链接。映射表是后续所有操作的基础，也是回滚依据，务必在动手前完成并留存。
站内互链：批量替换前先备份
站内页面互链数量大、集中在新站内部，适合用批量替换或链接修复工具处理。操作前导出页面内容备份，并保留映射表；替换按空间分批执行，每批完成后抽样检查，确认替换后的链接指向正确页面而非仅返回 200 状态。替换规则要精确匹配旧地址格式，避免误伤正文中恰好相似的文本。
外部系统深链：以重定向承接为主
外部系统、邮件模板、门户中保存的地址分散在多个系统里，逐个修改成本高且容易遗漏。可行做法是在旧域名侧配置重定向规则，把旧地址按映射表跳转到新地址，同时通知各系统负责人更新配置，逐步减少对重定向的依赖。重定向规则要覆盖带参数的深链，不能只处理首页。
附件与图片：按路径规则批量修复
附件和图片的引用地址通常有统一规律，可以按路径规则批量替换。修复后必须实际打开页面确认渲染正常，仅检查链接可达不够，图片显示异常往往在页面上才暴露。对嵌入在表格、宏或折叠块中的引用，抽查时要专门覆盖。
权限问题单独处理
权限导致的打不开，与链接本身无关。应核对迁移后的空间权限和页面权限是否与迁移前一致，按原权限结构恢复，而不是通过放开匿名访问或扩大权限范围让链接“能打开”。后者会带来信息暴露风险，也会掩盖真正的配置差异。
设定停止点
批量操作前保留可回滚的映射表与页面备份，并约定停止条件：当某一批次的异常比例明显高于预期，或出现替换后指向错误页面的情况，立即暂停该批次，回到映射表核对，确认规则无误后再继续。分批推进、每批留检查点，比一次性全量替换更可控。
验证恢复并防止下次迁移复发
处置完成后需要确认修复真正生效，而不只是操作执行完毕。验证按类型抽样回归：页面互链抽查不同空间和层级，附件图片抽查嵌入场景，外部深链抽查带参数的地址，权限相关链接用不同角色账号复测。有条件时对新站做一次全量失效链接扫描，把扫描结果与初始清单比对，确认剩余失效项都有明确归属。
验证通过的标准可以量化为三条：抽样链接能打开且指向正确页面，不是跳转到首页或错误页；附件与图片正常显示；外部系统深链能完成跳转并落到目标内容。三条同时满足，才认为该类链接恢复。
防复发的重点在流程前移。迁移前导出完整链接清单，作为迁移后的比对基线；迁移过程中同步建立旧新地址映射和重定向规则，不把这一步留到迁移结束后补；迁移后安排一次链接巡检，把结果纳入迁移验收清单，明确负责人和检查时点。验收清单中应包含链接抽样通过率、重定向覆盖率、附件显示抽查结果等可核验条目。
如果迁移目标是 ONES Wiki，ONES 提供 Confluence 替换方案，通过迁移工具与迁移服务将空间、页面、附件和权限结构迁移到 ONES Wiki，迁移数据包括用户、用户组、空间权限与页面权限，并支持页面正文、附件、图片、常用宏及批注的迁移。迁移后的链接巡检、失效项修复和验收确认，可以作为工作项纳入 ONES 的项目管理流程，按空间或批次分配负责人、设定检查时点并跟踪关闭状态，让链接校验成为迁移验收中可追踪的一环。旧链接重定向与内部链接改写的具体处理规则，建议在迁移方案确认阶段与实施方核实。
常见问题
迁移前就存在的失效链接，要不要一起修？
建议先分开统计。迁移前已失效的链接不计入本次迁移的问题范围，否则会高估影响面，修复工作量也会失真。可以在失效清单中增加一列“是否由本次迁移引起”，按证据标注。迁移前遗留的失效项可以单独列一个清理清单，按业务重要性排优先级，不与迁移修复混在同一批次处理。
没有条件做全量链接扫描时，抽样怎么抽才有代表性？
抽样要覆盖不同空间、不同页面层级和不同迁移批次，单一空间的样本不足以代表整体。可以按链接类型分层抽取：页面互链覆盖多级页面，附件图片覆盖正文、表格和宏中的嵌入场景，外部深链优先抽带参数的地址。每类样本量不必很大，但要能支撑“该类原因是否普遍存在”的判断。抽样结果记录链接地址、比对结论和所属批次，便于后续复核。
重定向规则要保留多久，什么时候可以下线？
重定向主要承接书签、历史邮件和外部系统中无法集中修改的旧地址，下线时间取决于这些旧地址的实际访问情况。可行做法是给重定向规则加访问统计，观察一段时间内仍被访问的旧地址集中在哪些系统，通知对应负责人更新配置，访问量降到很低后再评估下线。带参数的深链要单独统计，不能只看首页跳转量。下线前保留规则配置备份，避免误删后无法恢复。
批量替换后出现指向错误页面，怎么回退？
回退依赖操作前留下的备份和映射表。批量替换按空间分批执行时，每批完成后抽样检查链接是否指向正确页面，而不只是返回 200 状态。一旦发现某批次异常比例明显高于预期，立即暂停该批次，用备份恢复页面内容，回到映射表核对替换规则，确认规则无误后再重新执行。分批推进、每批留检查点，可以把回退范围控制在一批之内。
迁移目标是 ONES Wiki 时，链接处理要注意什么？
ONES 提供 Confluence 替换方案，通过迁移工具与迁移服务将空间、页面、附件和权限结构迁移到 ONES Wiki，迁移数据包括用户、用户组、空间权限与页面权限，并支持页面正文、附件、图片、常用宏及批注的迁移。迁移后的链接巡检、失效项修复和验收确认，可以作为工作项纳入 ONES 的项目管理流程，按空间或批次分配负责人并跟踪关闭状态。旧链接重定向与内部链接改写的具体处理规则，建议在迁移方案确认阶段与实施方核实。
