使用Ionic+Capacitor集成Keycloak开发Android应用遇白屏问题求助

我用Keycloak、Ionic（Angular）和Capacitor开发Android应用，网页端运行正常，但Android模拟器里启动就白屏。推测是启动时初始化Keycloak导致Capacitor无法访问Keycloak。

我知道可以自定义Keycloak adapter，但不知道怎么实现；另外还有keycloak-ionic依赖可选，不确定哪种方案更好。

相关代码 #

app.module.ts #

@NgModule({
  declarations: [
    AppComponent,
    ...
  ],
  imports: [
    BrowserModule,
    IonicModule.forRoot(),
    AppRoutingModule,
    HttpClientModule,
    ReactiveFormsModule,
    KeycloakAngularModule
  ],
  providers: [
    {
      provide: RouteReuseStrategy,
      useClass: IonicRouteStrategy
    },
    CookieService,
    {
      provide: APP_INITIALIZER,
      useFactory: initializeKeycloak,
      multi: true,
      deps: [KeycloakService],
    },
    {
      provide: ErrorHandler,
      useClass: GlobalErrorHandler,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

keycloak-init.factory.ts #

export function initializeKeycloak(keycloak: KeycloakService) {
  return () =>
    keycloak.init({
      config: {
        url: environment.keycloakApi,
        realm: 'quarkus',
        clientId: 'quarkus-app',
      },
      bearerPrefix: 'Bearer',
      initOptions: {
          onLoad: 'check-sso',
          silentCheckSsoRedirectUri:
              window.location.origin + '/assets/silent-check-sso.html'
      },
    });
}

当前依赖版本 #

"dependencies": {
  "@angular/common": "^14.0.0",
  "@angular/core": "^14.0.0",
  "@angular/forms": "^14.0.0",
  "@angular/platform-browser": "^14.0.0",
  "@angular/platform-browser-dynamic": "^14.0.0",
  "@angular/router": "^14.0.0",
  "@capacitor/android": "4.1.0",
  "@capacitor/app": "4.0.1",
  "@capacitor/core": "^4.1.0",
  "@capacitor/haptics": "4.0.1",
  "@capacitor/ios": "^4.1.0",
  "@capacitor/keyboard": "4.0.1",
  "@capacitor/status-bar": "4.0.1",
  "@ionic/angular": "^6.1.9",
  "keycloak-angular": "^12.0.0",
  "keycloak-js": "^19.0.1",
  "ngx-cookie-service": "^14.0.1",
  "rxjs": "~6.6.0",
  "tslib": "^2.2.0",
  "zone.js": "~0.11.4"
}

运行命令 #

ionic cap run android -l --external --target=Pixel_3_API_30 --host=<ip_adress> --port=8100  --public-host=<ip_adress> --open 

错误与警告 #

错误信息 #

Invalid ID 0x00000000.

警告信息 #

node_modules\keycloak-js\dist\keycloak.mjs depends on 'base64-js'. CommonJS or AMD dependencies can cause optimization bailouts.
    For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies

node_modules\keycloak-js\dist\keycloak.mjs depends on 'js-sha256'. CommonJS or AMD dependencies can cause optimization bailouts.
    For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies

1. 适配Capacitor环境调整Keycloak初始化 #

Capacitor的WebView和普通浏览器在Cookie存储、重定向逻辑上存在差异，当前的静默SSO配置可能导致初始化卡住，进而引发白屏。修改初始化逻辑：

import { Capacitor } from '@capacitor/core';

export function initializeKeycloak(keycloak: KeycloakService) {
  return () => {
    const isNative = Capacitor.isNativePlatform();
    
    return keycloak.init({
      config: {
        url: environment.keycloakApi,
        realm: 'quarkus',
        clientId: 'quarkus-app',
      },
      bearerPrefix: 'Bearer',
      initOptions: {
          onLoad: isNative ? 'login-required' : 'check-sso', // 原生环境禁用静默SSO
          silentCheckSsoRedirectUri: isNative 
            ? undefined 
            : window.location.origin + '/assets/silent-check-sso.html',
          pkceMethod: 'S256', // 强制使用PKCE适配原生WebView
        },
        enableBearerInterceptor: true,
        bearerExcludedUrls: []
    });
  }
}

• 原生环境改用login-required，避开静默SSO的重定向问题；
• 启用PKCE，这是原生应用OAuth2认证的标准方式，比Cookie更适配WebView；
• 登录Keycloak控制台，在对应客户端的重定向URI列表中添加模拟器IP或capacitor://localhost。

2. 方案选择：keycloak-ionic vs 自定义Adapter #

优先尝试keycloak-ionic #

这是社区维护的Ionic专用Keycloak适配包，已经封装了Capacitor环境的认证逻辑，比如将令牌存储到原生存储而非Cookie、处理WebView重定向，上手成本低，适合快速开发。安装后替换原有初始化逻辑即可。

自定义Adapter场景 #

如果需要高度定制认证流程（比如自定义令牌存储、多环境复杂适配），再考虑自定义Adapter：

1. 实现继承自KeycloakService的自定义服务；
2. 重写init方法，用Capacitor的Storage API替代Cookie存储令牌；
3. 适配WebView的重跳转逻辑，避免页面阻塞。

3. 消除CommonJS优化警告 #

在angular.json的build配置中添加允许的CommonJS依赖：

"architect": {
  "build": {
    "options": {
      "allowedCommonJsDependencies": [
        "base64-js",
        "js-sha256"
      ]
    }
  }
}

4. 额外排查步骤 #

• 验证模拟器网络：在模拟器浏览器中打开Keycloak服务器URL，确认网络连通；
• 查看WebView日志：用Chrome浏览器访问chrome://inspect连接模拟器WebView，查看具体JS错误；
• 异步初始化Keycloak：将初始化逻辑从APP_INITIALIZER移到AppComponent的ngOnInit中，避免阻塞应用启动。

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