Memento

Appearance

Github Page Error ​

Github Page报错_commonjsHelpers的问题 ​

问题描述 ​

在使用 Vitepress 构建的项目时，如果用到 按需引入 的组件，在线上环境会报错：

报错信息

_commonjsHelpers.XXXXXX.js file generated in the assets folder to Github Pages

Hydration completed but contains mismatches when using Github pages

原因分析 ​

问题排除

首先尝试在本地 build 后 yarn serve 运行，并不会报错。这时可以很自然的想到线上打包和本地打包的差异，合理怀疑是否是由于 Node.js 版本不一致造成的问题。

vitepress - Netlify、Vercel、AWS Amplify、Cloudflare 页面、渲染 中提到：

Node Version: 14 (or above, by default it usually will be 14 or 16, but on Cloudflare Pages the default is still 12, so you may need to change that)

本地使用的是 Node 16.x，线上是通过 Github Action 部署的。

先在本地切换到 Node 12.x 重新尝试运行：

sh
# 查看本地安装的所有nodejs版本
nvm list 

# 安装指定版本
nvm install 12

# 切换到指定版本
nvm use 12

# 卸载指定版本
nvm uninstall 12

# 显示当前版本
nvm current

结果显而易见，我忽略了 Vite 需要 Node.js > 14.18+, 16+ 才能正常运行。

接下来尝试把线上环境的 Node 版本与切换到与本地相同，找到 /.github/workflows/***.yml 文件:

yaml
# ...
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x] # 配置所需node版本
# ...

结果依然报错，至此可以排除是 Node.js 的问题造成该错误。

确认原因

这时在 vitepress 的 issue 中发现一个名为 Problems with uploading the _commonjsHelpers.XXXXXX.js file generated in the assets folder to Github Pages 的bug反馈。

在这个反馈下面尤大给出了正确答案：Bypassing Jekyll on GitHub Pages

_commonjsHelpers.XXXXXX.js file generated in the assets folder to Github Pages

Github Pages 默认是基于 Jekyll 构建，Jekyll 是一个将纯文本转换为静态网站的工具，它构建的网站下各种目录都是特定的以下划线开头命名的文件夹，例如 _layouts、_posts ，它会忽略掉其它的以下划线开头的文件夹和文件。

.nojekyll 就是告诉 Github Pages 当前网站不是基于 Jekyll 构建的，不要忽略掉下划线开头的文件和文件夹。

可见 .nojekyll 主要就是用于 Github Pages 这种有默认规则的网站部署平台，如果是部署在自己的服务器上，可以把它删掉。

反之，如果你的网站不是 Jekyll 构建的，要部署到 Github Pages ，并且包含下划线开头的文件或文件夹，那么你就需要在根目录添加一个 .nojekyll 空文件。

解决问题 ​

如上所说，只需要在 ***.github.io 的项目根目录中创建一个空的 .nojekyll 文件即可解决！🎉

提示

一些框架打包生成的 dist 文件已经为你创建好了这个空文件。例如：Nuxt