How I moved a Cloudflare Pages site to a custom domain without breaking the data feed

2026-11-21来源 dev.toEnglish

I just moved a static site from naming-cn.pages.dev to a domain I own. The DNS part took five minutes. The rest took two days — because the hard part wasn't pointing a hostname at Pages. It was folding the old hostname's ranking signals into the new one without breaking a JSON feed that a GitHub Action pulls every day.

The site in question publishes 109 Chinese surnames as open data. That last detail is why this migration was more than "add a CNAME and walk away": a CI job fetches /data/surnames.json from the site, so a careless whole-site redirect would have silently broken the data pipeline while everything still looked fine in a browser.

Here's what worked, including the three places where the obvious answer was wrong.

1. DNS: the cutover is quick, the cache is not

The root and www hostnames were A records pointing at an old Vercel deployment. I deleted both and replaced them with CNAMEs to naming-cn.pages.dev, proxied (orange cloud).

Then I checked the root domain from my own machine and it still resolved to the old Vercel IPs. For a few hours this looks exactly like a failed migration. It isn't. Authoritative DNS was already returning Cloudflare nodes; my local recursive resolver was simply holding the old TTL. Don't "fix" it by editing the records again — that just restarts the TTL clock. Query a public resolver, or wait it out.

2. A DNS record does not bind the domain to Pages

This one is easy to miss. Adding the CNAME doesn't attach the hostname to your Pages project. The root domain was already listed as active in my project's custom domains, but www was missing. I added it through the Cloudflare API, then found its validation status stuck at pending — a PATCH against the domain endpoint retried validation and cleared it. All three hostnames (root, www, and a pre-existing qiming subdomain) ended up active.

3. _redirects cannot redirect across hosts

This is the big one. My first instinct was a line in _redirects:

https://naming-cn.pages.dev/* https://liuxxiaojun.cn/:splat 301 

Pages ignores it. _redirects supports path-based redirects on the current host; it does not accept a protocol-bearing from. So the whole "redirect the old domain" plan has to move one layer up.

4. Edge middleware does the 301 — with an asset carve-out

Pages Functions run at the edge, in front of both static assets and HTML. The middleware redirects only the legacy host, and only for HTML requests; everything matching an asset extension passes through untouched:

const LEGACY_HOSTS = new Set(["naming-cn.pages.dev"]); const ASSET_RE = /\.(css|js|json|png|jpe?g|svg|webp|ico|woff2?|txt|xml|map)$/i; export async function onRequest(context) { const { request, next } = context; try { const url = new URL(request.url); if (LEGACY_HOSTS.has(url.hostname.toLowerCase()) && !ASSET_RE.test(url.pathname)) { url.hostname = "liuxxiaojun.cn"; url.protocol = "https:"; return Response.redirect(url.toString(), 301); } } catch (e) { /* malformed URL: pass through */ } return next(); } 

Preserving url.search (which url.toString() does for free) mattered more than I expected — several shared links carried tracking query strings.

Why the asset carve-out is the important line. My _routes.json already excludes .json and .csv from Functions, so the data feed never reaches this code. The regex is a second guarantee: even if I later loosen _routes.json, /data/surnames.json will keep returning 200 instead of starting an infinite redirect that no human would notice until the CI job failed. I also deliberately left www and qiming at 200 rather than redirecting them — both already emit a canonical pointing at the root domain, so they're duplicates, not competitors, and redirecting them adds a hop for no ranking gain.

5. The deployment flag that no longer exists

Every older tutorial will tell you to run pages deploy dist --functions functions. On current Wrangler that errors with Unknown argument: functions. Functions are now discovered automatically from the functions/ directory — but only relative to your current working directory. If you deploy from dist/, your middleware silently isn't in the bundle.

Two checks saved me here: run the deploy from the project root, and confirm the log contains Uploading Functions bundle. Without that line, the 301 isn't live no matter what the static upload says.

6. Canonicals, and the 7,000 replacements behind them

Redirects fix the hostname; they don't fix the URLs baked into your HTML. I ran a full replacement across 443 files — canonicals, og:url, JSON-LD, internal links, sitemaps, llms.txt, even the URLs printed inside code samples in the docs — about 7,000 occurrences of the old domain.

The split is worth stating explicitly: HTML pages 301 to the new domain; www and qiming stay 200 with canonicals pointing at the root; static data stays 200 everywhere. Aim for one canonical host, not "redirect absolutely everything."

7. Search Console: skip OAuth, use a TXT record

Adding the new domain as a Search Console property normally offers a Cloudflare OAuth shortcut. My API credentials didn't have the right scope, so I took the DNS TXT route: paste the verification value from the GSC wizard into a root-domain TXT record, verify through Google's DNS, done. One warning — don't delete that TXT record afterwards; removing it invalidates the property.

When submitting the sitemap, enter the full URL. sitemap.xml alone is reported as invalid. And if the dashboard says "couldn't fetch sitemap" but "Test live URL" can retrieve it and reports the page as indexable, the site is fine — that's a GSC-side status problem, not something to debug in your headers.

After that, a short IndexNow push for the changed URLs returned 202, and a forced commit to the sync workflow re-ran the CI job that pulls data from the new domain. Empty commits won't trigger Actions here — the workflow file has to actually change.

The verification I ran

  • Root, www, qiming, sitemap, and the JSON feed all return 200.
  • Legacy host HTML returns 301 with the correct Location, path and query preserved.
  • Legacy host /data/surnames.json returns 200 (the feed survived).
  • Canonical on the root domain is self-referential; AdSense tags are gone.
  • The dataset is still 109 rows / 16 fields after the CI re-run.

Migrating a Pages site is mostly bookkeeping. The part that isn't bookkeeping is deciding what not to redirect: your data endpoints and your alternate hostnames are part of the system, and a blanket 301 across all of them is a great way to break production quietly.

The dataset itself is at liuxxiaojun.cn if you want to see what survived the move.

原文:https://www.a8q9.cn/en/article/how-i-moved-a-cloudflare-pages-site-to-a-custom-domain-without-breaking-the-data-91df51.html

相关文章