StencilJS预渲染构建Hydrate报错：Cannot access 'getRenderingRef' before initialization

问题背景 #

使用StencilJS执行预渲染构建时，Hydrate过程抛出以下错误：

[ ERROR ]  Hydrate Error
           ReferenceError: Cannot access 'getRenderingRef' before initialization at stencilSubscription$1
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:4996:5) at createStore$2
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:5138:13) at createRouter
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:5148:42) at hydrateAppClosure
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:5529:1) at hydrateFactory
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:34029:3) at render
           (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:34296:9) at
           C:\Users\aleung\Desktop\project\dist\hydrate\index.js:34228:62 at new Promise (<anonymous>) at
           Object.hydrateDocument (C:\Users\aleung\Desktop\project\dist\hydrate\index.js:34220:33) at prerenderWorker
           (C:\Users\aleung\Desktop\project\node_modules\@stencil\core\compiler\stencil.js:9988:46)

当前关键配置：

• package.json构建命令：

"build": "stencil build --prerender --config stencil.config.ts",

• stencil.config.ts核心配置：

import { Config } from '@stencil/core';
import nodePolyfills from 'rollup-plugin-node-polyfills';

export const config: Config = {
    namespace: 'project',
    globalStyle: 'src/global/app.css',
    globalScript: 'src/global/app.ts',
    taskQueue: 'async',
    outputTargets: [
        {
            type: 'www',
            serviceWorker: null,
            baseUrl: 'https://myapp.local/',
        },
    ],
    rollupPlugins: {
        after: [nodePolyfills()],
    },
};

解决方案 #

1. 调整Rollup插件执行顺序 #

nodePolyfills放在after阶段会打乱Stencil内部模块的初始化逻辑，将其移至before阶段：

rollupPlugins: {
    before: [nodePolyfills()],
},

2. 移除不必要的Node环境Polyfill #

如果项目不需要Node.js专属API（如process、buffer），直接删除nodePolyfills相关配置：

// 删除导入语句
// import nodePolyfills from 'rollup-plugin-node-polyfills';

// 清空rollupPlugins配置
rollupPlugins: {},

3. 升级Stencil到最新稳定版 #

该错误可能是版本兼容性问题，执行命令升级：

npm install @stencil/core@latest --save-dev

4. 排查全局脚本的提前初始化代码 #

检查src/global/app.ts，确保没有在Hydrate完成前提前调用路由相关方法（如createRouter、路由订阅），将这类代码延迟到组件挂载后执行。

内容的提问来源于stack exchange，提问作者Tsun Yeung Leung