记 Valaxy GitHub Pages 部署失败排查记录

[YunYouJun]

起因

#167 @Seanium 发现 GitHub Pages 下的网站打开时会弹出下载，而非正常访问。

简单记录本次问题的排查与解决方案，以供参考。

也感谢过程中 @Seanium @kifuan @Rotten-LKZ 等群友参与讨论。

结论

先说结论，由于 vite-plugin-vue-layouts JohnCampionJr/vite-plugin-vue-layouts#27 为适配 vite-ssg dirStyles: nested 风格，对 route.children[0].path 进行了处理。这导致在 flat 模式下构建时会多生成一个名为.html 文件，该文件内容与 index.html 完全一致。

07039f8

过程

查找原因

经测试，此由于网页响应头 Content-Type: application/octet-stream 所导致，因此猜测由于生成后的 index.html 被识别为二进制文件导致。
且此时使用相同代码部署的 Vercel/Netlify/Cloudflare Pages 可正常访问。

对于 GitHub Pages 来说，会自动将 html 后缀名的文件识别为 Content-Type: text/html，但现在的表现确是失效了。

MIME types on GitHub Pages

• 猜测：html 中存在不标准的字符导致标签闭合而没有被 GitHub 识别为 HTML

  • 测试：修改 script (function(){})()（匿名函数立即执行改为普通脚本）
    结果：无效
  • 测试：格式化 html 文件重新上传
    结果：无效
  • 测试：修改 index.html 文件为最简单的 hello world
    结果：无效

• 猜测：.nojekyll 导致（GitHub Pages 默认支持 Jekyll，故存在一些特殊的匹配策略，如没有 .nojekyll 时无法访问 _ 开头的资源文件）

  • 测试：添加/移除 .nojekyll
  • 结果：无效

• 猜测：GitHub Pages 目前支持两种部署方案，采用了 GitHub Actions（Beta） 部署导致

  • 测试：回退为经典的 Branch 部署
  • 结果：无效

• 测试：尝试拷贝 dist 文件夹内部内容，新建仓库直接部署。

  • 结果：这时竟然可以成功部署了。（但这踩到了另一个坑，使用 mac 全选拷贝文件的时候，没有拷贝到 . 开头的隐藏文件 .html。）

这令人百思不得其解。

在不断测试的过程中，又发现了一些其他的表现。

• /index.html 可以直接访问
• Valaxy 0.14.2 可正常部署，而 Valaxy 0.14.3 失败

本以为和 GitHub 的识别策略有关，但此说明和 Valaxy 的构建产物有关。

v0.14.2...v0.14.3

0.14.2-0.14.3 的变动很少，可以快速看到。

这也说明勤发版本是好事，可以快速 diff 版本差异。

变动中有两部分代码可能导致该问题。

• 将 vite-ssg dirStyles 值从 nested 改为 flat
• 兜底页面 [...all].vue 配合 vite-ssg dirStyles: flat 添加了 / 结尾路径的适配逻辑

onBeforeMount(() => {
  // compatible for post url ends with slash
  if (route.path.endsWith('/'))
    router.replace(route.path.slice(0, -1))
})

但是 Content-Type 作为响应头在网页加载逻辑前便相应了，理应与此无关。但以防万一，GitHub Pages 提前做了魔法的预渲染之类。if (route.path !== '/' && route.path.endsWith('/')) 测试无效。

那么最后一种可能性便是 nested -> flat。

构建两种方式产物，对比根目录内容。此时发现 flat 下会相比 nested 多出一个 .html 文件，猜测由此导致。
删除测试，访问成功。

且该情况只发生在 GitHub Pages，Vercel/Netlify/Cloudflare Pages 等部署的相同站点等可正常访问，故猜测是 GitHub Pages 的特殊策略解析了 .html 且其优先级高于 index.html。

解决方案

原因找到，但我们还需找到为何 Valaxy 依赖的 vite-ssg 在 dirStyles: 'flat' 下会生成 .html。

查看 vite-ssg 相关关键代码：

https://github.com/antfu/vite-ssg/blob/16fd2f4275d84584829ee858ccdd94e2122f5d60/src/node/build.ts#L180-L186

const relativeRouteFile = `${(route.endsWith('/')
  ? `${route}index`
  : route).replace(/^\//g, '')}.html`

const filename = dirStyle === 'nested'
  ? join(route.replace(/^\//g, ''), 'index.html')
  : relativeRouteFile

前三行的排版有点让人误解因此导致，换个更清晰的写法：

// '/' -> '/index'
const relativeRouteFileName = route.endsWith('/') ? `${route}index` : route
// '/index' -> '/index.html'
const relativeRouteFile = const relativeRouteFileName.replace(/^\//g, '')  + '.html'

// '/index.html' -> '/index.html'
const filename = dirStyle === 'nested'
  ? join(route.replace(/^\//g, ''), 'index.html')
  : relativeRouteFile

没问题。那么问题可能出在 ssg 过程中用到的其他插件。

测试 vitesse 构建同样存在该问题，会生成 .html。

• 猜测： [...all].vue 用于 catch 404 页面。
  • 测试：删除 [...all].vue
  • 结果：仍旧生成 .html，排除 vite-plugin-pages

vite-plugin-vue-layouts 对 vite-plugin-pages 的路由进行了一层处理。

• 猜测：vite-plugin-vue-layouts 的 layout 导致
  • 测试：移除 vite-plugin-vue-layouts 相关内容
  • 结果：成功，不再生成 .html

查看 vite-plugin-vue-layouts 路由处理相关代码。

https://github.com/JohnCampionJr/vite-plugin-vue-layouts/pull/27/files#diff-794c8e48b70de4c72e3298503a21db4726e03ed0a0fad770c3c6ed9eaabbe917

关键词 vite-ssg nested 等可以找到一个相关 Issue fix path in children | vite-plugin-vue-layouts。
查看代码变更：

// src/RouteLayout.ts
function getClientCode(importCode: string) {
  const code = `
${importCode}
export function setupLayouts(routes) {
- return routes.map((route) => {
+ return routes.map(route => {
    return { 
      path: route.path,
      component: layouts[route.meta?.layout || 'default'],
-     children: [route],
+     children: [ {...route, path: ''} ],
    }
  })
}
`
  return code
}
export default getClientCode

• 猜测：'/' 的 children: [ {...route, path: ''} ] 导致
• 测试：编写移除的兼容代码

const homeRoute = routes.find(route => route.path === '/')
if (homeRoute && homeRoute.children) {
  const childRoute = homeRoute.children.find(child => child.path === '')
  if (childRoute)
    Object.assign(childRoute, generatedRoutes.find(route => route.path === '/'))

• 结果：成功

由于该问题本质来自 vite-plugin-vue-layouts 对 vite-ssg 的适配，可向 vite-plugin-vue-layouts 提 PR 修改。
最终，我创建了 fix: extra .html generated when vite-ssg dirStyles flat | vite-plugin-vue-layouts 以解决该问题。

并通过 07039f8 临时解决 Valaxy 构建的问题。

经验

由于该问题的表现十分玄学，且 .html 与 index.html 完全一致，弹出下载时也并不会显示文件名，容易导致开发者将问题的重点放在了 index.html 上，而很难发现。在此过程中也存在一些其他值得注意，避免走弯路的经验。

• mac 下最好将文件夹显示隐藏文件打开（cmd + shift + .）避免复制文件疏忽
• 依次缩小问题范围，如最小可复现 demo，或版本 diff，避免如无头苍蝇乱撞
• 可以联想是否为同工作区下的其他文件干扰导致
• 规律地记录测试的可能性，避免重复返工

[MengNianxiaoyao]

0.16.1版本又开始这样了，一打开就是下载。加上index.html就能访问，但是加载完就会变回原链接，刷新就是下载

[YunYouJun]

绝了，被人改回去了…… JohnCampionJr/vite-plugin-vue-layouts@2270f71

[MengNianxiaoyao]

不行，还是会生成.html文件

[YunYouJun]

我的意思是 JohnCampionJr/vite-plugin-vue-layouts#132 (comment) 我之前修复的 PR 被人改回去了，现在就是导致有这个问题。

[YunYouJun]

vite-plugin-vue-layouts 已修复，升级了新的依赖。