[Bug report] cleanUrls: 客户端访问无后缀 URL 被补成 .html，与托管层 URL 规范化冲突导致无限重定向循环

[MEMZ-CHROER]

Bug report

Description

开启 cleanUrls: true 后，VuePress 生成的 SSR 链接是无后缀的（目录式，如 /tanks/）。但客户端路由对无后缀路径的推断仍会强制补 .html（如访问 /tanks 会被规范成 /tanks.html）。

当站点部署在会自动规范化 URL 的静态托管平台（如 Vercel）时，VuePress 的客户端规范化与托管层的规范化规则互相冲突，形成无限重定向循环：

/tanks          ← 用户访问（无后缀）
  ↓ VuePress 客户端：无后缀 → 强制补 .html
/tanks.html
  ↓ 托管层重写：.html → 目录 index
/tanks/
  ↓ 托管层/浏览器：带尾斜杠目录 → 归一为无后缀
/tanks
  ↓ VuePress 客户端：又补 .html
... 无限循环 → ERR_TOO_MANY_REDIRECTS

Steps to reproduce

1. 配置 cleanUrls: true
2. 内容用目录式结构：tanks/README.md → 产物 tanks/index.html，路由 /tanks/
3. 部署到 Vercel（或任何会对无后缀/尾斜杠做 301 规范化的静态托管）
4. 浏览器访问 /tanks（无后缀）
5. 观察：客户端把 /tanks 规范成 /tanks.html，托管层再弹回目录形态，陷入循环

注：直接访问 /tanks/（带斜杠）正常。问题仅在无后缀输入时触发——这正是 cleanUrls 期望支持的 URL 形态。

Expected behavior

• cleanUrls: true 开启时，客户端路由解析应尊重 cleanUrls：无后缀路径不应被强制补 .html（应保持无后缀或原样匹配）。
• 或者：提供配置项/路由选项，让用户能完全控制 URL 规范化行为，避免与托管平台的规范化规则冲突。

Environment info

• Browser: Edge
• vuepress: 2.0.0-rc.26
• @vuepress/bundler-vite: 2.0.0-rc.26
• @vuepress/theme-default: 2.0.0-rc.120

[MEMZ-CHROER]

---

🔍 补充：完整根因分析 + 最小复现仓库（帮助开发者快速定位）

1. 根因源码定位

@vuepress/shared/src/utils/routes/inferRoutePath.ts（真实实现，rc.26）：

const inferRoutePath = (rawPath) => {
  if (!rawPath || rawPath.endsWith("/")) return rawPath
  let routePath = rawPath.replace(/(^|\/)README.md$/i, "$1index.html")
  if (routePath.endsWith(".md")) {
    routePath = `${routePath.substring(0, routePath.length - 3)}.html`
  } else if (!routePath.endsWith(".html")) {
    routePath = `${routePath}.html`   // ← 无后缀路径被强制补 .html
  }
  if (routePath.endsWith("/index.html")) {
    routePath = routePath.substring(0, routePath.length - 10)  // index.html → 目录
  }
  return routePath
}

实测输出（require('@vuepress/shared').inferRoutePath）：

输入	输出	说明
/tanks	/tanks.html	❌ 无后缀被强制补 .html
/tanks/	/tanks/	✅ 带斜杠原样放行
/	/	✅
/tanks/design.html	/tanks/design.html	✅ 已有后缀
tanks/README.md	/tanks/	✅ 目录页
tanks/design.md	/tanks/design.html	单页

该函数被 @vuepress/core 的 inferPagePath 调用（构建期）：
foo/bar.md → /foo/bar.html，README/index.md → /

2. 问题本质

• 构建产物是 tanks/index.html + tanks/design.html（目录式）
• cleanUrls: true 让 SSR 链接生成无后缀形式
• 但 客户端 vue-router 在访问无后缀 URL（如 /tanks）时，经 inferRoutePath 推断会把它重定向到 /tanks.html
• 而 /tanks.html 在托管层（如 Vercel 的 trailing-slash/clean-urls 处理）又被规范化回目录 /tanks/ → 再被去斜杠 → 回到 /tanks → 无限循环

preparePagesRoutes（@vuepress/core） 注册的 redirect 别名里没有无后缀形式，所以无后缀输入永远走不到正确页面：

// preparePagesRoutes 的 redirects 集合：
redirectsSet.add(decodeURI(path))          // /tanks/
if (/\/$/.test(path)) {
  redirectsSet.add(path + 'index.html')    // /tanks/index.html
}
if (pathInferred !== null) {
  redirectsSet.add(pathInferred)           // /tanks/（目录页）或 /tanks/design.html
}
if (filePathRelative !== null) {
  redirectsSet.add(ensureLeadingSlash(filePathRelative)) // /tanks/README.md
}
// ← 没有 /tanks（无后缀）这个别名！

3. 最小复现仓库

my-vuepress-repro/
├─ package.json
└─ docs/
   ├─ .vuepress/
   │  └─ config.js
   └─ tanks/
      └─ README.md

package.json

{
  "name": "vuepress-cleanurls-repro",
  "private": true,
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
  "devDependencies": {
    "@vuepress/bundler-vite": "2.0.0-rc.26",
    "@vuepress/theme-default": "2.0.0-rc.120",
    "vuepress": "2.0.0-rc.26"
  }
}

docs/.vuepress/config.js

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'

export default {
  cleanUrls: true,
  theme: defaultTheme({
    navbar: [
      { text: 'Tanks', link: '/tanks/' },
    ],
  }),
  bundler: viteBundler(),
}

docs/tanks/README.md

# Tanks

Tanks 目录页。

4. 复现步骤

1. yarn install && yarn build → 产物 docs/.vuepress/dist/tanks/index.html
2. 部署到 Vercel（默认 cleanUrls + trailing slash 规范化）→ 部署到 Vercel 的任意项目，或本地用 npx serve dist 观察
3. 浏览器访问 /tanks（无后缀）：
   • 客户端 vue-router 把 /tanks 重定向到 /tanks.html
   • Vercel 再把 /tanks.html 301 回 /tanks/
   • 浏览器/托管层把 /tanks/ 去斜杠 → /tanks
   • 无限循环 → ERR_TOO_MANY_REDIRECTS

访问 /tanks/（带斜杠）正常。问题仅在 cleanUrls 期望支持的无后缀形态 下触发。

5. 期望修复方向

1. 客户端尊重 cleanUrls：cleanUrls: true 时，客户端路由对无后缀路径不应经 inferRoutePath 强制补 .html，应保持无后缀直接匹配目录路由
2. 或 在 preparePagesRoutes 的 redirects 里补充无后缀别名（/tanks → /tanks/），让无后缀输入能在 VuePress 内部闭环，不依赖托管层

6. 影响范围

任何 cleanUrls: true + 目录式内容 + 部署在会做 URL 规范化的托管（Vercel / Netlify / Cloudflare Pages / GitHub Pages 自定义）都可能触发。不局限于 Vercel。

[MEMZ-CHROER]

本仓库是 VuePress v1 历史仓库（最后维护 2024-05）。用户实际使用的 vuepress@next（2.0.0-rc.26+）由 vuepress/core 发布维护。此 issue 已在 vuepress/core 重新提交：#（待创建）。

[MEMZ-CHROER]

已迁移到正确的活跃仓库 vuepress/core：

• 新 issue：[Bug report] clean URLs (无后缀访问目录页) 在客户端被转成不存在的 .html，导致 404 / 无限重定向循环 vuepress/core#1719
• 修复 PR：fix(client): fallback to directory route when .html route does not exist vuepress/core#1720

本仓库（vuejs/vuepress）是 VuePress v1 历史仓库，此 issue 关闭。