升级至Angular 14后Handsontable HotTableModule加载白屏报错

问题根因 #

两类报错均由Handsontable依赖版本与Angular 14环境不匹配导致：

• Uncaught TypeError: webpack_require.h is not a function：Angular 14内置Webpack 5版本移除了旧版公共模块API，适配Angular 11及更早版本的Handsontable依赖旧版Webpack暴露的require.h接口做模块注入，运行时找不到对应方法直接中断应用初始化，触发白屏。
• Uncaught TypeError: Cannot read properties of undefined (reading 'MIXIN_NAME')：@handsontable/angular封装包与handsontable核心包版本号不一致，或封装包版本未适配Angular 14的Ivy渲染器规则，模块加载阶段无法拿到核心包导出的MIXIN常量，初始化失败。

修复步骤 #

• 完全卸载现有Handsontable相关依赖
  项目根目录执行对应包管理命令：

  # npm环境
  npm uninstall handsontable @handsontable/angular
  
  # yarn环境
  yarn remove handsontable @handsontable/angular
  

• 安装适配Angular 14的指定版本
  Handsontable 12.x系列是官方明确适配Angular 14的版本，必须保证核心包和Angular封装包版本完全一致，禁止混装：

  # npm环境
  npm install handsontable@12.3.0 @handsontable/angular@12.3.0 --save-exact
  
  # yarn环境
  yarn add handsontable@12.3.0 @handsontable/angular@12.3.0 --exact
  

  注意：不要安装13.0.0及以上版本的Handsontable，高版本最低支持Angular 15，装完依然会出现兼容报错。

• 校验模块引入配置
  打开引入HotTableModule的模块文件（通常为app.module.ts或业务特征模块），按如下规则修正配置：

  import { NgModule } from '@angular/core';
  import { BrowserModule } from '@angular/platform-browser';
  import { HotTableModule } from '@handsontable/angular';
  // 必须引入模块注册方法
  import { registerAllModules } from 'handsontable/registry';
  import { AppComponent } from './app.component';
  
  // 注册Handsontable所有官方模块
  registerAllModules();
  
  @NgModule({
    declarations: [AppComponent],
    imports: [
      BrowserModule,
      HotTableModule // 确认模块已加入imports数组
    ],
    bootstrap: [AppComponent]
  })
  export class AppModule { }
  

• 清理全量缓存后重启项目
  Angular 14的持久化构建缓存会残留旧依赖的编译产物，必须完全清理后再启动，否则修改不生效：

  # 删除依赖目录和锁文件
  rm -rf node_modules package-lock.json yarn.lock
  # 重新安装全量依赖
  npm install
  # 清理Angular构建缓存
  ng cache clean
  # 启动开发服务
  ng serve
  

• 特殊场景排查
  如果项目用@angular-builders/custom-webpack做了自定义Webpack配置，检查配置中是否存在针对handsontable的模块别名、依赖externals或tree-shaking裁剪规则，这类规则会干扰Handsontable的模块导出，触发同类报错。

内容的提问来源于stack exchange，提问作者Samuel Dennis