---
title: "Fix GSC \"Alternate Page with Proper Canonical\" in Astro"
description: "Fix Google Search Console \"Alternate page with proper canonical tag\" in Astro and Cloudflare Workers with trailing-slash links, 301s, and build checks."
image: "https://zengliangyi.com/_astro/gsc_astro_canonical_cover_en.CAmKIxPv_ZmYvij.webp"
---

In Google Search Console’s page indexing report, “Alternate page with proper canonical tag” looks like a status you can ignore. When my site hit it, URL Inspection showed:

- User-declared canonical: `https://zengliangyi.com/en/blog/tag/tailwind-css/`

- Google-selected canonical: same as user-declared

- Referring page: `https://zengliangyi.com/en/blog/tag/tailwind-css/`

The canonical and the referring page look like the same address, so which URL was the alternate? The inspected URL was `/en/blog/tag/tailwind-css` without the trailing slash. Google crawled it, read a canonical pointing at the slash version, and classified it as an alternate. The referring page field says something more important: Google found that non-slash URL on my own site.

> 💡 Where to find the referring page in Search Console

> Click the affected URL in the report -> click  Inspect URL  -> expand the  Discovery  card -> check  Referring page . This shows which page gave Googlebot the uncanonical link.

## What the status means

The status tells you three things:

- Google crawled URL A;

- A’s canonical points at URL B;

- Google agreed, indexed B, and left A out of results.

From an indexing point of view the canonical works and B is indexed. The problem is how many A URLs exist and where they come from. A few old external links are harmless. If every page’s navigation and breadcrumbs emit A, Google finds a new batch of duplicates with every crawl, crawl budget goes to duplicates, and the alternate-page count keeps growing.

## Root cause: canonicals had the slash, links did not

The site runs on Astro and deploys to Cloudflare Workers. URL formats were inconsistent across the output:

| Location | Format |

| --- | --- |

| Build output | `/blog/tag/css/index.html` (Astro default `build.format: 'directory'`) |

| `<link rel="canonical">` | trailing slash |

| `sitemap-0.xml` | trailing slash |

| `<a href>` in pages (nav, tags, pagination) | no slash, e.g. `/en/blog/tag/tailwind-css` |

| `BreadcrumbList` JSON-LD `item` | no slash |

| `BlogPosting` author URL, `llms.txt` | no slash |

Astro’s `trailingSlash` defaults to `'ignore'`, so both forms reach the same page and nothing fails during development. Components build paths with helpers such as `localizedPath('/about', locale)`, which return the non-slash form. The sitemap and canonical come from the build output and carry the slash. Each side was correct on its own; together they declared one URL and linked another.

After the build, the site’s HTML contained **14,172** internal page links missing the trailing slash.

## Slash or no slash

Google has no preference and only asks for consistency. The slash form won because of the output structure:

- Astro’s directory build emits `/slug/index.html`, so slash URLs map directly to files;

- canonicals and the sitemap already used the slash, so only links needed to change;

- indexed canonical URLs stay the same, and Google does not need to reselect them.

Going the other way would mean changing `build.format`, canonicals, the sitemap, and already indexed URLs at once.

## Why a 301 alone falls short

The obvious fix is a 301 at the edge from the non-slash URL to the slash URL. Google would consolidate signals, but if internal links stay unchanged:

- every crawl of an internal link costs two requests, the old URL and the redirect target;

- Search Console trades “Alternate page” entries for a long list of “Page with redirect”;

- every internal click adds a redirect round trip for users.

So internal links must point at the canonical URL directly, and the 301 only handles external links and URLs Google already knows.

## The fix, from link source to build check

### 1. One path helper

`src/lib/canonical-path.ts` appends a slash only to internal page paths. It skips static files, APIs, and external URLs, and keeps query strings and fragments:



```ts
const   FILE_EXTENSION_RE   =  
    /  \.  (?:xml  |  json  |  txt  |  md  |  html  |  htm  |  png  |  jpe  ?  g  |  webp  |  gif  |  svg  |  ico  |  webmanifest  |  woff2  ?|  ttf  |  otf  |  eot  |  css  |  js  |  mjs  |  cjs  |  map  |  pdf  |  zip  |  wasm)  $  /  i  ;  
  
  const   NON_PAGE_PREFIX_RE   =   /  ^  \/  (?:api  |  \.  well-known  |  _astro  |  images  |  assets)(?:  \/  |$  )  /  ;  
  
  export   function   ensureTrailingSlash  (  href  :   string  )  :   string   {  
    if   (  !  href   ||   !  href.  startsWith  (  '/'  )   ||   href.  startsWith  (  '//'  ))   return   href;  
    // Split off #hash and ?query, then test only the pathname  
    // '/about#faq' -> '/about/#faq', '/rss.xml' stays unchanged  
    // ...  
  }
```



Paths like `/.well-known/api-catalog` have no extension but are not pages. The prefix list excludes them so they do not gain a slash and return 404.

### 2. Structured data and text indexes

The breadcrumb component renders visible links and `BreadcrumbList` JSON-LD, and both go through `ensureTrailingSlash`:



```ts
const   schemaItems   =   items.  map  ((  item  )   =>   ({  
    name: item.label,  
    url:   new   URL  (  ensureTrailingSlash  (item.href   ??   Astro.url.pathname), siteConfig.url).  toString  (),  
  }));
```



The `BlogPosting` author URL and the post and project URLs in `llms.txt` get the same treatment. Search engines discover URLs from structured data too, so fixing `<a href>` alone is not enough.

### 3. Rewrite links in the built HTML

Navigation, tag clouds, and pagination live in dozens of components, and fixing each by hand invites misses. The site already had an integration that walks every HTML file in `astro:build:done` to produce Markdown versions for AI agents, so the rewrite happens there:



```js
for   (  const   htmlPath   of   htmlFiles) {  
    const   rawHtml   =   await   readFile  (htmlPath,   'utf8'  );  
    const   htmlContent   =   normalizeInternalPageHrefs  (rawHtml);  
    if   (htmlContent   !==   rawHtml) {  
      await   writeFile  (htmlPath, htmlContent,   'utf8'  );  
    }  
    // Markdown is then generated from the normalized HTML  
  }
```



A future component that hard-codes a non-slash link still ships a corrected link, and the Markdown versions stay consistent.

### 4. A 301 fallback in the Cloudflare Worker

`wrangler.toml` sets `run_worker_first = true`, so every request passes through the Worker entry. The 301 lives in that entry function instead of a dashboard redirect rule, which keeps it versioned with the code:



```js
if   (  
    (request.method   ===   'GET'   ||   request.method   ===   'HEAD'  )   &&  
    url.pathname   !==   '/'   &&  
    !  url.pathname.  endsWith  (  '/'  )   &&  
    !  FILE_EXTENSION_RE  .  test  (url.pathname)   &&  
    !  NON_PAGE_PREFIX_RE  .  test  (url.pathname)  
  ) {  
    return   Response.  redirect  (url.origin   +   url.pathname   +   '/'   +   url.search,   301  );  
  }
```



Verified after deployment:



```bash
$   curl   -sI   https://zengliangyi.com/blog  
  HTTP/2   301  
  location:   https://zengliangyi.com/blog/
```



### 5. Build-time checks against regressions

A one-time fix does not stop a future component from emitting non-slash links. `scripts/verify-build.mjs` gained two checks that fail the build on any violation:

- every `BreadcrumbList` `item` must end with `/`;

- every internal page `<a href>` in the HTML must end with `/`.

Following the repository’s convention, the check ran first against the unfixed output to confirm it fails. It reported the non-slash breadcrumb items and all 14,172 internal links. After the fix and a rebuild, it passed. A check that has only run against working output proves nothing about catching the problem.

## What changes in Search Console

- New pages: no non-slash links exist on the site, so Google stops discovering duplicates there;

- Known old URLs: on recrawl they return 301 and move from “Alternate page” to “Page with redirect”, which is expected;

- When reviewing the report, switch the filter from “All known pages” to “All submitted pages” to see only sitemap URLs. Redirects and alternates should not appear there.

`http://` and `www.` URLs that redirect to the `https://` apex appear under “Page with redirect” for the same reason and need no action.

## Summary

“Alternate page with proper canonical tag” shows that canonicals work, and also that the site is feeding Google duplicate URLs. The order of work:

- Pick one URL format based on the build output;

- Use the canonical URL directly in internal links, structured data, and text indexes;

- Add an edge 301 for external links;

- Check the output at build time so it does not regress.

After the fix, active submission helps search engines recrawl sooner; see [Google Indexing in Astro: Incremental Cache-Driven Submissions](/en/blog/google-indexing-incremental-cache/). The same post-build artifact verification pattern also catches silent metadata 404s when [precompiling Astro WebP images on Cloudflare Workers](/en/blog/astro-cloudflare-compile-webp-images/).

Share:

##  Related Posts

[##  Google Indexing API in Astro: Incremental Sitemap Cache

How to fix Google indexing deadlocks in static Astro sites using incremental cache-driven API submissions, Git SHA hashing, and sitemap lastmod timestamps.          Leon Zeng       October 13, 2026      4 min read

#Astro

#SEO

#Google](/en/blog/google-indexing-incremental-cache/)    [##  Astro Cloudflare Workers: Precompile WebP & Avoid 404s

Replace slow /_image Worker transforms in @astrojs/cloudflare with imageService: compile, transcode WebP via Sharp, and fix og:image 404s with getImage().          Leon Zeng       November 15, 2026      5 min read

#Astro

#Performance

#Frontend

#SEO](/en/blog/astro-cloudflare-compile-webp-images/)

##  From writing to code

Explore ChatCrystal, KeelDesk, n8n workflows and daily learning notes on my GitHub. Questions about the implementation are welcome.

[Visit my GitHub](https://github.com/ZengLiangYi)

```json
{
  "@context": "https://schema.org",
  "@id": "https://zengliangyi.com/#website",
  "@type": "WebSite",
  "name": "ZengLiangYi Blog",
  "alternateName": [
    "Leon Zeng",
    "Zeng Liangyi",
    "ZengLiangYi",
    "zengliangyi.com"
  ],
  "url": "https://zengliangyi.com",
  "description": "Frontend engineering, AI coding and open-source practice",
  "inLanguage": "en",
  "author": {
    "@id": "https://zengliangyi.com/#person"
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Fix GSC \"Alternate Page with Proper Canonical\" in Astro",
  "description": "Fix Google Search Console \"Alternate page with proper canonical tag\" in Astro and Cloudflare Workers with trailing-slash links, 301s, and build checks.",
  "url": "https://zengliangyi.com/en/blog/gsc-alternate-page-trailing-slash/",
  "image": "https://zengliangyi.com/_astro/gsc_astro_canonical_cover_en.CAmKIxPv_ZmYvij.webp",
  "datePublished": "2026-10-29T00:00:00.000Z",
  "dateModified": "2026-11-15T00:00:00.000Z",
  "inLanguage": "en",
  "keywords": [
    "Astro",
    "SEO",
    "Google"
  ],
  "articleSection": "Astro",
  "isPartOf": {
    "@id": "https://zengliangyi.com/#website"
  },
  "author": {
    "@id": "https://zengliangyi.com/#person",
    "@type": "Person",
    "name": "曾亮懿",
    "alternateName": [
      "Leon Zeng",
      "Zeng Liangyi",
      "ZengLiangYi",
      "夜雪闻竹"
    ],
    "jobTitle": "AI Native Developer",
    "knowsAbout": [
      "AI Native Development",
      "AI Agents",
      "Model Context Protocol",
      "TypeScript",
      "React",
      "Full-Stack Development",
      "Developer Tools"
    ],
    "url": "https://zengliangyi.com/en/about/",
    "email": "contact@zengliangyi.com",
    "image": "https://zengliangyi.com/branding/zeng-liangyi-avatar.png",
    "address": {
      "@type": "PostalAddress",
      "addressLocality": "深圳",
      "addressRegion": "广东",
      "addressCountry": "CN"
    },
    "sameAs": [
      "https://github.com/ZengLiangYi",
      "https://x.com/LeonZeng_",
      "https://bsky.app/profile/yizel9.bsky.social",
      "https://www.reddit.com/user/ExternalActive4238/",
      "https://juejin.cn/user/1669474445171547",
      "https://blog.csdn.net/2201_75708499",
      "https://www.linkedin.com/in/zeng-liangyi/",
      "https://gravatar.com/radangelb905e883e0"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "ZengLiangYi Blog",
    "url": "https://zengliangyi.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://zengliangyi.com/favicon-96x96.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://zengliangyi.com/en/blog/gsc-alternate-page-trailing-slash/"
  }
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "name": "Fix GSC \"Alternate Page with Proper Canonical\" in Astro",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Is \"Alternate page with proper canonical tag\" an error in Google Search Console?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No. It means Google crawled a duplicate URL and indexed the URL named by its canonical tag instead. What needs attention is where the duplicate URL comes from, because it keeps consuming crawl budget."
      }
    },
    {
      "@type": "Question",
      "name": "Should URLs end with a trailing slash or not?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Google has no ranking preference; consistency is what matters. Astro’s default directory build emits /slug/index.html, so the trailing-slash form matches the output and is the cheapest to adopt."
      }
    },
    {
      "@type": "Question",
      "name": "Is a 301 redirect alone enough?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No. If internal links still point at the non-slash URL, crawlers request it and then follow the 301 every time, and Search Console lists those URLs under \"Page with redirect\". Point every internal link at the canonical URL first, and keep the 301 as a fallback for external links."
      }
    },
    {
      "@type": "Question",
      "name": "Do homepage links on social profiles need a trailing slash?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Not for the root domain. https://example.com and https://example.com/ both send GET / over HTTP. Only sub-paths distinguish the two forms."
      }
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "name": "Breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://zengliangyi.com/en/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog",
      "item": "https://zengliangyi.com/en/blog/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Fix GSC \"Alternate Page with Proper Canonical\" in Astro",
      "item": "https://zengliangyi.com/en/blog/gsc-alternate-page-trailing-slash/"
    }
  ]
}
```
