Building a redirect map for a site migration

A migration moves URLs, and every moved URL needs a signpost. The redirect map is that signpost: a table pairing each old address with the new one it should lead to. Done right, it is the difference between a migration that consolidates your search presence and one that scatters it across a forest of 404s.

Step 1 — inventory the old URLs

You cannot map what you have not listed. Pull the old URL set from every source you have, because each one sees a different slice:

• The old sitemap.xml — the pages you intended to be crawled.
• Search Console — the Pages report and the top linked URLs, which show what Google actually indexed and what the web links to.
• Server access logs — the URLs that receive real traffic, including ones you forgot existed.
• Analytics — landing pages that earned sessions.
• An internal crawl — every link your own site still points at.

Merge and de-duplicate. That combined list is your inventory.

Step 2 — match one to one

For each old URL, pick the single best new target. Never let a rule fan out to “everything goes to the homepage”: users and crawlers land on a page that does not answer their intent, and the relevance signal of the original URL is wasted.

Old URL	Right target	Wrong target
/blog/old-post	/blog/new-post (same topic)	/
/products/widget	/shop/widget	/products
/help/getting-started	/docs/getting-started	/
/events/2024-conf	/events/2025-conf	/events
/legacy-promo (no equivalent)	410 Gone if truly dead	/

The rule is: exact page first, then the closest parent category, then — only when nothing is equivalent — a genuine 404 or 410. A 410 is the honest signal for content you have deliberately removed.

Step 3 — preserve the query string

Query strings carry tracking parameters, filters and pagination. Many redirect rules drop them by default, which silently breaks campaigns and any deep-linked state. Append the query string explicitly:

# 保留查询串：$is_args 提供问号（如果有的话），$args 是原参数
location = /old-page {
  return 301 https://example.com/new-page$is_args$args;
}

# 正则捕获路径段，同时保留查询串
location ~ ^/blog/(.*)$ {
  return 301 https://example.com/articles/$1$is_args$args;
}

Only strip the query string deliberately, and only when the parameters are known to be worthless.

Step 4 — apply rules in one layer

Redirects usually exist at the edge (a CDN) and at the origin (the web server). If both layers define rules, they can stack or fight. Decide once — either the edge is authoritative and the origin serves plain content, or the opposite — and keep the rules in a single place you can review.

Step 5 — verify the map after the migration

Turn the map into a test. The check below reads a two-column list of old and new URLs and reports the final status for each:

while read -r from expected; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -L "$from")
  echo "$from -> $expected : $code"
done < redirect-map.csv

Every line should end in 200. Anything else is a map entry to fix.

Post-migration checklist

• Every old URL returns a single hop to a 200.
• No rule points at another redirect (no chains).
• Internal links reference final URLs, not redirected ones.
• The sitemap lists only final URLs.
• Canonical tags point at the destination URL.
• Query-string variants survive the hop where they matter.
• Content with no equivalent returns 404 or 410, never a homepage redirect.

Common mistakes

The blanket homepage redirect. The fastest way to lose the value of a migration is to point every old URL at /.

Redirecting to a URL that redirects again. Chains appear when a second migration stacks on the first. Point rules straight at the final destination.

Forgetting the query string. A redirect that drops ?utm_source= or ?page=3 breaks tracking and pagination without any visible error.

Mixing schemes and hosts. http to https and www to apex rules need to be decided once and applied consistently, or every request takes an extra hop.

Not updating internal links or the sitemap. Every internal link that still points at an old URL adds a hop for users and crawlers.

Skipping the post-migration sweep. Chains and dead ends surface only when a second change lands. Re-run the map check after every subsequent migration.

Where this tool fits

The redirect chain checker follows a URL hop by hop, showing the status code, the Location header and the timing at each step, so a broken map entry is obvious before it reaches production. Once the map is clean, run your final URLs through the sitemap validator to confirm every listed page resolves.