TypeScript导入KeycloakAuthorization报错：找不到模块'keycloak-js/authz'

问题描述 #

在TypeScript项目中导入Keycloak 24的KeycloakAuthorization时，使用代码：

import KeycloakAuthorization from 'keycloak-js/authz';

出现报错：

Cannot find module 'keycloak-js/authz' or its corresponding type declarations.

已确认package.json中包含该子模块的exports配置，tsconfig.json的moduleResolution已设置为node，但仍无法正常识别。

复现步骤 #

git clone https://github.com/fschick/Keycloak.ASPNet.Angular.git
cd Keycloak.ASPNet.Angular
git checkout main-fs-update
cd source/frontend/
npm install
npm run start

问题原因 #

核心问题是Keycloak 24的keycloak-js包类型声明不完整：虽然官方在package.json中配置了exports字段指向authz子模块，但对应的TypeScript类型定义文件（.d.ts）没有同步导出该子模块的类型信息，导致TypeScript编译器无法识别这个导入路径。此外，Angular的构建链（基于webpack）可能对模块解析有额外限制，进一步放大了这个类型缺失的问题。

修复方案 #

方案1：补全类型声明+调整导入路径 #

1. 修改导入路径为包内的实际文件路径：

   import KeycloakAuthorization from 'keycloak-js/dist/keycloak-authz.min.js';
   

2. 在项目根目录创建types/keycloak-js/index.d.ts文件，补充类型声明补丁：

   declare module 'keycloak-js/authz' {
     export default import('keycloak-js/dist/keycloak-authz').default;
   }
   

3. 确保tsconfig.json的typeRoots包含自定义类型目录：

   "typeRoots": ["./node_modules/@types", "./types"]
   

方案2：版本回退或升级 #

暂时回退到Keycloak 23版本（该版本的authz模块类型声明完整），或者等待Keycloak官方发布修复补丁后升级到新版本。

方案3：调整Angular构建配置 #

在angular.json的build.options中添加preserveSymlinks: true，避免模块解析时的路径歧义：

"build": {
  "options": {
    "preserveSymlinks": true,
    // 其他配置...
  }
}

Issue提交建议 #

问题属于Keycloak官方包的类型定义缺陷，应向Keycloak项目提交Issue。提交时需包含：

• Keycloak 24版本keycloak-js/authz子模块类型声明缺失的问题描述
• 复现步骤
• 环境信息（TypeScript版本、Angular版本）
• 报错截图或日志

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