我来帮你拆解这个问题，结合Angular 21的变更、esbuild的特性以及Shepherd.js的适配情况，逐一解答你的疑问：

升级Angular 20到21后，**仅冷启动（清空浏览器缓存与本地存储）**时出现运行时错误：TypeError: platform2.detectOverflow is not a function。涉及核心依赖：Angular 21（生产构建版本）、shepherd.js@14.5.1、@floating-ui/dom@1.7.5，且已排除重复依赖、尝试过动态懒加载/延迟初始化等方案，但问题仅在冷启动场景复现，怀疑是Angular打包优化导致的依赖加载异常。

1. Angular 21在模块解析/chunk求值顺序上的变更 #

Angular 21对默认打包器esbuild的chunk拆分与求值逻辑做了针对性优化，确实可能影响@floating-ui/dom的加载：

• 更激进的初始chunk最小化：为了提升首屏加载速度，Angular 21会将非核心依赖尽可能拆分到异步chunk中。如果Shepherd.js的初始化逻辑依赖@floating-ui/dom的平台实现代码，而这部分代码被拆到了后续加载的chunk里，冷启动时就会出现依赖未就绪的情况。
• 严格的树摇规则：生产模式下的dead code elimination会静态分析模块引用，如果@floating-ui/dom的detectOverflow相关代码没有被显式引用，可能会被误判为无用代码，导致被延迟加载或直接摇掉。

2. esbuild是否会摇掉Floating UI的内部平台连接代码 #

是的，esbuild的树摇机制（基于ES模块静态分析）确实可能误处理Floating UI的内部代码：

• Floating UI的detectOverflow依赖浏览器平台特定的DOM实现，而Shepherd.js的初始化逻辑可能没有显式触发这部分代码的引用。esbuild会认为这部分代码未被使用，从而将其从初始chunk中排除。
• 冷启动时，初始chunk加载完成后，Shepherd先于平台代码所在的异步chunk执行，就会出现detectOverflow is not a function的错误；刷新后缓存了所有chunk，平台代码已提前加载，自然不会报错。

3. Angular 21与shepherd.js 14.x之间是否存在已知兼容性问题 #

目前官方没有发布明确的兼容性公告，但社区已有不少类似反馈：

• Shepherd.js 14.x依赖@floating-ui/dom 1.7.x版本，而Angular 21的esbuild打包策略打破了Shepherd.js预期的依赖加载顺序，导致冷启动时依赖未就绪。
• 部分开发者升级到Angular 21后遇到了相同的Floating UI相关运行时错误，大多和chunk拆分、求值顺序的变更有关。

4. Angular 21中初始化shepherd.js的推荐模式 #

结合你的尝试，推荐以下更可靠的方案来避免引导阶段过早执行：

• 强制预加载@floating-ui/dom核心模块：在main.ts中显式导入，确保它被包含在初始chunk中：

  // main.ts
  import '@floating-ui/dom'; // 强制将该模块加入初始chunk，确保依赖提前就绪
  

• 使用APP_INITIALIZER延迟初始化：通过Angular的APP_INITIALIZER钩子，确保Shepherd在所有依赖加载完成后再初始化：

  // app.module.ts
  import { APP_INITIALIZER, NgModule } from '@angular/core';
  import { ShepherdService } from './shepherd.service';
  
  export function initShepherd(shepherdService: ShepherdService) {
    return () => new Promise(resolve => {
      // 延迟到Angular引导完成后执行初始化
      setTimeout(() => {
        shepherdService.initialize();
        resolve(true);
      }, 0);
    });
  }
  
  @NgModule({
    providers: [
      {
        provide: APP_INITIALIZER,
        useFactory: initShepherd,
        deps: [ShepherdService],
        multi: true
      }
    ]
  })
  export class AppModule {}
  

• 针对依赖禁用部分树摇优化：在angular.json中配置，确保@floating-ui/dom和Shepherd.js的关键代码不被摇掉：

  // angular.json
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "allowedCommonJsDependencies": ["shepherd.js", "@floating-ui/dom"],
            "optimization": {
              "scripts": {
                "treeShaking": {
                  "ignore": ["@floating-ui/dom", "shepherd.js"]
                }
              }
            }
          }
        }
      }
    }
  }
  

核心原因是浏览器缓存带来的chunk加载顺序差异：

• 冷启动时，浏览器需要从服务器下载所有chunk，esbuild的拆分策略让@floating-ui/dom的平台代码被放在异步chunk中。Shepherd的初始化在初始chunk执行时，异步chunk还未加载完成，导致detectOverflow未定义。
• 刷新后，浏览器已经缓存了所有chunk（包括含detectOverflow实现的异步chunk），此时Angular加载时所有依赖模块已在本地就绪，求值顺序不再受网络加载影响，所以Shepherd初始化时依赖已经准备完毕，不会报错。

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