How to Fix Astro Redirect Settings When They Don’t Work [Static Site SEO]#

Why Redirects Are Important for SEO#

• Avoiding duplicate content: When incorrect and correct URLs coexist, evaluation gets dispersed!!
• Link equity inheritance: With 301/308 redirects, you can transfer backlink evaluation to the new URL!!
• Crawl efficiency optimization: Reduce unnecessary 404s and save crawl budget!!

TIP

Google distinguishes between “permanent (301/308)” and “temporary (302)” redirects to transfer evaluation. Choose the status code according to your purpose!

Prerequisites#

• Astro v4 (SSG mode)
• Cloudflare Pages hosting (confirmed to work similarly on Vercel)

Method ①: Define redirects in astro.config.*#

This method adds redirects to the Astro configuration file. It’s officially recommended and easy to manage (important), so it’s sufficient for a small number of redirects!!

export default defineConfig({
  redirects: {
    // ① Path movement within the same site (default 301)
    "/posts/old-slug": "/posts/new-slug",

    // ② Dynamic routes are also OK (parameter names must match)
    "/blog/[...slug]": "/articles/[...slug]",

    // ③ When you want to specify status code explicitly
    "/note": {              // 308 = permanent POST allowed
      status: 308,
      destination: "/posts/note"
    },

    // ④ To external URL
    "/docs": "https://example.com/docs"
  }
});

• Advantages: Complete within Astro. HTML with <meta http-equiv="refresh"> is automatically generated during SSG build.
• Disadvantages: Writing many rules bloats the configuration file.

Method ②: Using vercel.json (Also available on Cloudflare Pages)#

If you need more detailed conditional branching or hostname-based routing, vercel.json is convenient.

{
  "redirects": [
    {
      "source":  "/posts/old-slug",
      "destination": "/posts/new-slug",
      "permanent": true         // 308
    },
    {
      "source":      "/blog/:year/:month/:slug",
      "destination": "/posts/:slug",
      "statusCode":  301
    },
    {
      "source":      "/docs/:path*",
      "destination": "https://example.com/docs/:path*",
      "permanent":   true
    },
    {
      "source": "/:path*",
      "has": [
        { "type": "host", "value": "old.example.com" }
      ],
      "destination": "/legacy/:path*",
      "statusCode": 302
    }
  ]
}

• Advantages
  • Advanced features like wildcards and host conditions.
  • Configuration files can be separated for easier maintenance.
• Disadvantages
  • Depends on trailingSlash settings, requiring attention to trailing slash forced removal behavior.

WARNING

Redirects defined in vercel.json remove trailing slashes by default. If you’ve specified trailingSlash: "always", consistency verification is required!

Which Should You Choose?#

For my site, since I always add trailing slashes, I adopted Method ①.

Summary#

• Choose the correct status code to transfer evaluation without loss.
• Astro’s standard redirects is the most convenient.
• For advanced conditional branching or bulk settings, vercel.json is useful. However, pay attention to compatibility with trailingSlash.

Here’s how to change trailingSlash settings in Astro!!

設定方法

docs.astro.build

Reference Links#

• Astro Official Routing Guide
• Vercel Redirect Guide