Angular 17中(appCheck/already-initialized)错误的解决方法

问题背景 #

创建新Angular SSR项目，通过schematics引入@angular/fire，使用Firestore、Storage、Authentication服务，已配置App Check并在Firebase控制台添加调试令牌。

当前app.config.ts初始化代码：

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(
      provideFirebaseApp(() => initializeApp(environment.firebase)),
      provideAppCheck(() =>
        initializeAppCheck(getApp(), {
          provider: new ReCaptchaEnterpriseProvider(environment.siteKey),
          isTokenAutoRefreshEnabled: true,
        })
      )
    ),
  ]
}

遇到的问题：

• 首次执行npm start报错「document未定义」
• 无修改刷新页面后恢复正常，但修改代码后刷新触发(appCheck/already-initialized)错误，必须重启终端重新运行npm start才能解决
• 尝试通过检查现有应用实例初始化App Check，问题依旧：

provideAppCheck(() =>
  initializeAppCheck(
    getApps().length === 0 
      ? initializeApp(environment.firebase)
      : getApp(), 
    {
      provider: new ReCaptchaEnterpriseProvider(environment.siteKey),
      isTokenAutoRefreshEnabled: true,
    }
  )
)

解决方案 #

1. 解决「document未定义」错误 #

ReCaptcha依赖浏览器环境的document对象，SSR服务器端渲染时不存在该对象，需区分环境初始化App Check：

import { isPlatformBrowser } from '@angular/common';
import { inject, PLATFORM_ID } from '@angular/core';

// 在provideAppCheck中添加环境判断
provideAppCheck(() => {
  const platformId = inject(PLATFORM_ID);
  const app = getApp();
  if (isPlatformBrowser(platformId)) {
    return initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider(environment.siteKey),
      isTokenAutoRefreshEnabled: true,
    });
  }
  // 服务器端使用调试提供者
  return initializeAppCheck(app, {
    provider: new DebugAppCheckProvider(environment.appCheckDebugToken),
    isTokenAutoRefreshEnabled: true,
  });
})

2. 解决「appCheck/already-initialized」错误 #

热模块替换（HMR）时App Check会被重复初始化，需先检查是否已存在实例：

provideAppCheck(() => {
  const platformId = inject(PLATFORM_ID);
  const app = getApp();
  try {
    // 尝试获取已初始化的App Check实例
    return getAppCheck(app);
  } catch {
    // 未初始化则创建新实例
    if (isPlatformBrowser(platformId)) {
      return initializeAppCheck(app, {
        provider: new ReCaptchaEnterpriseProvider(environment.siteKey),
        isTokenAutoRefreshEnabled: true,
      });
    } else {
      return initializeAppCheck(app, {
        provider: new DebugAppCheckProvider(environment.appCheckDebugToken),
        isTokenAutoRefreshEnabled: true,
      });
    }
  }
})

3. 完整配置示例 #

import { ApplicationConfig, importProvidersFrom, inject, PLATFORM_ID } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { provideFirebaseApp, initializeApp, getApp, getApps } from '@angular/fire/app';
import { provideAppCheck, initializeAppCheck, getAppCheck, ReCaptchaEnterpriseProvider, DebugAppCheckProvider } from '@angular/fire/app-check';
import { environment } from './environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(
      provideFirebaseApp(() => {
        // 确保Firebase应用只初始化一次
        return getApps().length === 0 ? initializeApp(environment.firebase) : getApp();
      }),
      provideAppCheck(() => {
        const platformId = inject(PLATFORM_ID);
        const app = getApp();
        try {
          return getAppCheck(app);
        } catch {
          if (isPlatformBrowser(platformId)) {
            return initializeAppCheck(app, {
              provider: new ReCaptchaEnterpriseProvider(environment.siteKey),
              isTokenAutoRefreshEnabled: true,
            });
          } else {
            return initializeAppCheck(app, {
              provider: new DebugAppCheckProvider(environment.appCheckDebugToken),
              isTokenAutoRefreshEnabled: true,
            });
          }
        }
      })
    ),
    // 按需添加其他Firebase服务配置：provideFirestore、provideStorage、provideAuth等
  ]
};

内容的提问来源于stack exchange，提问作者TR4C3S 0F 45H