wxsm's space

Oct 25, 2020

记一次艰难的 Debug

这是一次关于本博客的 Debug 经历,过程非常曲折。关键词:Vue / SSR / 错配

不知道从哪篇博文开始,博客在直接从内页打开时,或者在内页刷新浏览器时,会报以下错误:

app.73b8bd4d.js:8
DOMException: Failed to execute 'appendChild' on 'Node': 
This node type does not support this method.

screenshot

该错误:

  1. 只会在 build 模式出现;
  2. 只会在发布上 Github Pages 后出现;
  3. 只会在某些博文中出现;
  4. 只会在直接从链接进入该博文,或者在该博文页面刷新时出现。

该错误带来的影响,会导致页面上的所有 JavaScript 功能全部失效,具体来说是与 Vue.js 相关的功能。如:导航链接(因为使用了 Vue-Router),评论框,一些依赖于 Vue.js 的 VuePress 插件,等等。

# 主题?

初次看到这个报错时,我的第一想法是:是不是我不经意间在哪里调用了 appendChild 这个方法导致的?因为我的博客使用了我自己发布的主题,有可能是我哪个地方写得不好导致了这个问题。

但是,再三检查主题代码 vuepress-theme-mini (opens new window) 后,我并没有发现任何可疑之处。

实际上我也不太相信这个错误是由我的主题导致的,因为查看错误抛出处的源码时发现这些代码都不像是我写的。

# 插件?

另一个可疑之处,则是插件。具体来说,是以下 3 个插件:

  1. valine 用于展示评论
  2. vuepress-plugin-flowchart 用于绘制流程图
  3. vuepress-plugin-right-anchor 用于显示浮动的目录

我 Google 了很多次,最后在 vuepress/issues/1692 (opens new window) 里,有一句话引起了我的注意:

Just a hint: Another common mistake is to use dynamic vue components that should render client side but forget to ignore them in static builds... 99% of those issues in our projects were missing <ClientOnly>. So try:

<ClientOnly>
  <NonSSRFriendlyComponent/>
</ClientOnly>

这个 99% 的表述让我不得不引起重视,审视上述插件的代码以后,发现其确实没有加入 <ClientOnly>,难道这就是问题所在?

然而经过实践,并不行。再三确认所有 fork 版本里面已经正确使用了 <ClientOnly>,错误依然存在。

该 issue 里面提到的另一点:

I had the same problem, and then I found out it had to do with document

enhanceApp.js

if (typeof window !== 'undefined') { // add this line
  window.document.xxx
}

我同样再三确认已经修正,依旧不能解决错误。

# YAML?

以上两处都无法找到问题,我有点迷惘了。因此开始漫无目的地寻找出错页面的共同点,以试图定位问题。最后,我发现:出现错误的页面貌似大多数都有 yaml 高亮的代码块。当然只是大多数,依然存在其它个例。

我尝试将 yaml 格式去除,即将:

```yaml
# ...
```

写为:

```
# ...
```

然后部署上线,错误神奇地消失了!

但是,我还没有开心过一分钟,立即发现:错误是消失了,但其带来的副作用依然存在:Vue.js 依然处于崩溃状态,任何功能都无法使用

这让我感到很沮丧:这种 SPA 带来的体验还不如最原始的 <a> 标签。

因此,我尝试对主题做出了一些小改动,将导航栏的跳转链接全部换成了普通的 <a> 标签。这件事情如果做到这一步,在某种层面上来说也算是解决了吧。除了以下一些问题持续地让我感到难受:

  1. 不能使用 yaml 高亮;
  2. 不能使用 Vue-Router
  3. 无法追根朔源的痛苦。

# 路径?

虽然从使用性的层面上来说问题算是解决了,但是我还是很在意以上几点。因此仍在持续地探究问题根源。

后来,我在 netlify 上看到了这样一个帖子:VuePress deployment on Netlify succeeds, but experience errors when reloading specific pages (opens new window)

作者所提到的问题基本跟我一模一样:

Hi, I have a VuePress generated static website deployed on Netlify, I am currently running into errors like:

Failed to execute 'appendChild' on 'Node': This node type does not support this method. only when reloading inner pages (i.e, not homepage.).

I have searched for similar issues on GitHub and it seems that it is related to Vue’s failing hydration as described here: nuxt.js/issues/1552 (opens new window), and here: vuepress/issues/1692 (opens new window).

However, I didn’t come across these issues when I’m in my local environment (both in dev mode and in production mode), I only run into these issues when I deploy my site to Netlify.

Confusing…

这简直有一种抓住了救命稻草的感觉!激动地往下翻,作者还说他找到了问题所在:

New update! So I converted all of my file names and directory names to lowercase and it actually solved the problem!

我立刻开始检查出问题的页面是否存在类似问题。然而,很遗憾,我的页面所有 url 都是小写的,不存在任何大写字符。

我又想,是不是有任何加载的资源里面出现了大写字符,导致了加载失败,因而产生错误?

结果再次让人感到遗憾:从我的域名中加载的所有资源,均没有出现大写字符的情况,更没有任何一个资源加载失败。

调查再次陷入僵局。

# SSR?

Google 之余,偶然看到了这样一个 issue: vue/issues/6874 (opens new window),作者提到,当 SSR 发生「错配」时,Vue.js 应用会出现类似「宕机」的表现。他希望可以通过参数控制这个行为,即当 SSR 出现「错配」时,允许用户选择自己想要的行为。如忽略 SSR 的结果并以客户端渲染结果覆盖,或仅提出 warning 而不是整个挂掉。

而 yyx 则认为,只要不是白屏 (white screen),则都能接受。

此时我不想深入探讨这个行为。我只想知道,我的问题到底是不是跟这个有关?

VuePress 有一个插件 vuepress-plugin-dehydrate (opens new window),可以实现禁用所有 JavaScript,将页面作为纯静态 HTML 使用。在测试中我发现,禁用「客户端接管」以后页面确实没有问题了。但我觉得这不是废话吗?这个实验完全没有任何意义啊。

后面,我想到一个办法,即通过创建一个全新的仓库,不加任何主题与插件,看看 yaml 高亮是否会出现问题。

# 复现

我在 Github 新建了一个仓库,用最少的配置搭建出来了一个 VuePress 程序。尝试:

  1. 添加一个包含 yaml 高亮的页面,没有出现问题
  2. 将出现问题的博文整篇添加进去,没有出现问题
  3. 将博客的所有主题、插件、博文均导入到新仓库中,依然没有出现问题

走到这一步我头都大了,好像只剩下最后一个区别了,即自定义域名。要是再不能复现,干脆我把博客迁移过来算了。

然而,最出乎意料的是,在添加自定义域名,并通过域名访问后,问题复现了!后来,我逐步将所有东西复原到步骤 1 的状态,即最简 VuePress + 一个 yaml 高亮的页面,问题持续复现。

到这里,问题就很明朗了:

这就是 Cloudflare 的锅!(我的域名托管在 Cf)

# 解决

最终定位到问题以后,解决似乎变得顺利成章了起来。我将 Google 关键词换成了 Cloudflare + VuePress,没有发现有价值的信息。再换成 Cloudflare + Vue + SSR,找到了这篇博文:Cloudflare and Vue SSR; Client Hydration Failures (opens new window),里面详细地描述了作者遇到的问题(基本跟我一致)以及解决思路。

按照他的说法,他的应用之所以出现这个问题,是因为 Cloudflare 启用了一种叫 AutoMin 的优化,会自动对静态资源 (JavaScript / CSS / HTML) 再做进一步的压缩。然而 HTML 中被去掉了的 <!-- --> 注释则是问题的关键所在:这是 v-if 节点用来成功挂载的重要组成部分。

至于如何发现,由于错误提示基本没有调试价值,尝试了各种办法后,最终通过将本地编译的静态 HTML 与服务器上面的 HTML 进行逐行比对,最终发现区别。

知道了这点我立马就打开 Cloudflare 控制台试图关闭该配置,但经过一番寻找后发现,该配置从来就没有打开过!

不过没关系,既然如此,那我也来对比一下。最终得到的有意义的区别,我本地编译的版本是:

ssh user@host

Cloudflare 返回的版本是:

ssh <a href="/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="b6c3c5d3c4f6ded9c5c2">[email&#160;protected]</a>

西巴。原来它还有这个功能。淦!

这个功能在 CloudFlare 上叫 Email Address Obfuscation,会自动保护出现在 HTML 上的邮箱地址,相当于打码处理。但是,正是因为它,导致了 Vue.js 出现 SSR 错配,进而导致网站崩溃。

我把该功能关掉后,问题就消失了。

# 总结

追根朔源,问题的根本与我先前的猜想大相庭径:与主题、插件、yaml 等均无关,而是因为 HTML 中出现了类似邮件地址的文本,被 Cloudflare 转换了。

当然,我承认这是因为我在 SSR 方面的经验不足,才走了这么多弯路。以后再发现这种问题,我一定第一步就做比对。

不过,在这个过程中,我也确实感受到了 Vue.js 在 SSR 方面的一些不足(我认为的):

  1. 错配即崩溃,Vue.js 直接放弃接管;
  2. 错误提示过于晦涩;
  3. 用户对于该行为没有选择权。

从另一层面来说,能够最终找到问题根源并通过最简单的方式将其解决,这种感受很爽。在这个过程中我有很多理由去放弃,但我没有。对于这点我感到很开心。


Last Updated: 16 days ago