执行Analogjs项目npm run dev遇Promise兼容错误，求技术指导

问题场景 #

创建基础Analog.js项目时：

• 执行npm create analog@latest正常完成
• 执行npm i安装依赖无问题
• 执行npm run dev启动服务时出现以下错误：

服务器端点可通过“/api”路径访问。
➜ Local: http://localhost:5173/
➜ Network: use --host to expose

4:43:26 pm [vite] Error when evaluating SSR module
/node_modules/@angular/core/fesm2022/core.mjs: failed to import "rxjs"
|- TypeError: Method Promise.prototype.then called on incompatible receiver [object Object]
at ZoneAwarePromise.then ()
at node:internal/per_context/primordials:440:35
at new Promise ()
at new SafePromise (node:internal/per_context/primordials:408:29)
at node:internal/per_context/primordials:440:9
at Array.map ()
at arrayToSafePromiseIterable (node:internal/per_context/primordials:437:5)
at node:internal/per_context/primordials:453:21
at new Promise ()
at primordials.SafePromiseAll (node:internal/per_context/primordials:452:3)

4:43:26 pm [vite] Error when evaluating SSR module
~analog/entry-server: failed to import "/node_modules/@angular/core/fesm2022/core.mjs" |- TypeError: Method Promise.prototype.then called on incompatible receiver [object Object]
at ZoneAwarePromise.then ()
at node:internal/per_context/primordials:440:35
at new Promise ()
at new SafePromise (node:internal/per_context/primordials:408:29)
at node:internal/per_context/primordials:440:9
at Array.map ()
at arrayToSafePromiseIterable (node:internal/per_context/primordials:437:5)
at node:internal/per_context/primordials:453:21
at new Promise ()
at primordials.SafePromiseAll (node:internal/per_context/primordials:452:3)

解决方案 #

1. 调整Node.js版本 #

该错误源于Node.js 20.x早期版本（如20.6.0）引入的SafePromise与Angular的ZoneAwarePromise冲突：

• 降级到Node.js 18.x LTS版本（长期支持版，兼容性更稳定）
• 或升级到Node.js 20.9.0及以上版本（官方已修复该Promise兼容问题）

2. 修改Zone.js配置（无需更换Node版本） #

在项目的vite.config.ts中添加配置，禁用Zone.js对Promise的全局补丁：

import { defineConfig } from 'vite';
import analog from '@analogjs/platform';

export default defineConfig({
  plugins: [analog()],
  optimizeDeps: {
    esbuildOptions: {
      define: {
        'globalThis': 'globalThis'
      }
    }
  },
  server: {
    fs: {
      allow: ['..']
    }
  },
  // 添加以下配置
  resolve: {
    alias: {
      'zone.js': 'zone.js/dist/zone.js'
    }
  },
  define: {
    'ZoneAwarePromise': 'Promise'
  }
});

3. 清理依赖并重新安装 #

• 删除项目根目录下的node_modules文件夹、package-lock.json文件
• 执行npm cache clean --force清除npm缓存
• 重新执行npm install安装依赖

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