A relaunch changes your URLs, and search engines and visitors still use the old ones. If those old URLs return 404, you lose the traffic and the signals that took years to build. The fix is not complicated, but it needs to be done in a careful order and tested before launch day.
In this tutorial you will build a URL inventory of the old site, write a mapping table, turn it into an nginx map, and test every row with a Bash script. You will also get a pre-launch checklist and a short monitoring plan for the first days after launch.
Prerequisites: shell access, curl, an nginx server for the new site, and a list of your old URLs.
Step 1: Build the URL inventory
Start from what exists, not from what you remember. Combine several sources:
- The XML sitemap of the old site.
- A crawl of the old site with a crawler of your choice, exported as CSV.
- URLs with traffic or backlinks from your analytics, Search Console and a backlink tool.
Merge them into one file, one URL per line, and remove duplicates:
cat sitemap_urls.txt crawl_urls.txt analytics_urls.txt \
| sed 's/[?#].*$//' \
| sort -u > old_urls.txt
wc -l old_urls.txt
The sed line strips query strings and fragments. If your site uses query strings for real content (for example ?id=12), keep them and handle them separately.
Step 2: Create the mapping table
For each old URL, decide what happens:
- 301: the content has a new home. Redirect to the closest matching new page.
- 410: the content is gone for good and has no equivalent. Tell search engines so.
- Keep: the URL stays the same, no rule needed.
Use a simple CSV with three columns, old_path,new_path,status:
/leistungen/seo.html,/services/seo/,301
/blog/2019/old-post,/blog/old-post/,301
/impressum.html,/imprint/,301
/aktion-2018,,410
Rules for good mapping:
- Redirect to the most relevant page, not to the homepage. Mass redirects to the homepage are often treated like soft 404 errors.
- Point directly to the final URL. Avoid chains such as A to B to C.
- Keep a note why each 410 is a 410.
Step 3: Turn the table into an nginx map
nginx can read a map block and apply it with one if-free rule. First generate the map file from the CSV:
awk -F, '$3==301 {printf " %s %s;\n", $1, $2}' mapping.csv > redirects_301.inc
awk -F, '$3==410 {printf " %s 1;\n", $1}' mapping.csv > gone_410.inc
Then use the two include files in your configuration:
map $uri $redirect_target {
default "";
include /etc/nginx/redirects_301.inc;
}
map $uri $is_gone {
default 0;
include /etc/nginx/gone_410.inc;
}
server {
listen 80;
server_name example.com;
if ($is_gone) {
return 410;
}
if ($redirect_target) {
return 301 $redirect_target;
}
# normal site config follows
}
Using if only to return is a safe use in nginx. Keep the map entries exact: a path in the map must match $uri exactly, including the trailing slash. Run nginx -t before you reload.
Step 4: Test every row with Bash
Do not trust the table, test it. This script requests each old path on the staging host and compares the status code and the redirect target:
#!/usr/bin/env bash
# usage: ./test_redirects.sh https://staging.example.com mapping.csv
base="$1"
file="$2"
fail=0
while IFS=, read -r old new status; do
[ -z "$old" ] && continue
result=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$base$old")
code=${result%% *}
target=${result#* }
if [ "$code" != "$status" ]; then
echo "FAIL $old: expected $status, got $code"
fail=1
elif [ "$status" = "301" ] && [ "$target" != "$base$new" ]; then
echo "FAIL $old: expected target $base$new, got $target"
fail=1
fi
done < "$file"
[ "$fail" -eq 0 ] && echo "All rows OK" || exit 1
Also check for chains: every 301 target must itself return 200 and not another redirect.
awk -F, '$3==301 {print $2}' mapping.csv | sort -u | while read -r p; do
code=$(curl -s -o /dev/null -w "%{http_code}" "https://staging.example.com$p")
[ "$code" != "200" ] && echo "Target $p returns $code"
done
Run both scripts until they print nothing but "All rows OK".
Step 5: Pre-launch checklist
- The staging site is blocked from indexing (password or
noindex), and the production site is not. - Remove the staging
noindexand anyDisallow: /fromrobots.txton launch day. - Canonical tags on the new pages point to the new production URLs.
- The new XML sitemap lists only URLs that return 200.
- Internal links use the new URLs directly, not the redirects.
- Redirects and 410 rules are active and tested.
- Analytics and Search Console are set up for the new site.
The two most expensive mistakes are launching with the staging noindex still in place and launching with a robots.txt that blocks everything. Check both manually in the browser source and at /robots.txt right after go-live.
Step 6: Monitor the first 72 hours
After launch, check these things at set times (right after launch, after 24 hours, after 72 hours):
- Search Console, page indexing report: watch for a rise in "Not found (404)" and "Page with redirect".
- Search Console, sitemaps: confirm the new sitemap was read without errors.
- Server logs: list the most requested URLs that return 404.
awk '$9 == 404 {print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20
Each URL in this list is either a missing row in your mapping or a broken internal link. Add the missing redirects, rerun the test script, reload nginx.
Expect some ranking movement in the first weeks. A clean 301 mapping lets the signals move to the new URLs, but search engines need time to process it. Do not change the structure again in this period.
Summary
Build the inventory from several sources, map each URL to a 301 or a 410, generate the nginx maps from one CSV, and test every row with a script before launch. The CSV is your single source of truth, and the test script is your safety net.
Top comments (0)