引入了 core-js 仍报 Promise is not defined 怎么解决

一、问题表象定位与四步排查流程

该错误通常爆发在老旧设备或运行环境中，例如老旧 Android 系统的内置 WebView、低版本 iOS（< 10）、IE11 或定制化工控大屏浏览器。在这些环境中原生不存在 Promise 对象，开发者虽然安装了 core-js 并在代码中写了引入代码，页面加载时依然直接白屏崩溃。

排查该问题不需要盲目尝试各种配置，通过下面清晰的诊断决策树，可以快速锁定问题节点：

解决的第一步是确认“构建产物内到底有没有包含 Promise Polyfill 代码”。打开打包输出的最终 JS 文件（如 dist/bundle.js 或 chunk-vendors.js），搜索关键词 es.promise 或 core-js/modules/es.promise：

• 若产物中完全搜索不到相关实现：说明构建工具在编译期判定不需要注入 Polyfill，需重点检查 Babel 的 targets 与 useBuiltIns 配置。
• 若产物中明确存在相关代码：说明 Polyfill 已经被打包进去了，问题出在运行时加载顺序或全局作用域可见性（如局部别名隔离）。

二、原因一：Babel targets 设置过高导致 Polyfill 被过滤

这是现代前端工程中最普遍的原因。在 @babel/preset-env 中，Babel 不是无条件把整个 core-js 打包进来的，而是根据项目的 targets（或 .browserslistrc、package.json 中的 browserslist 字段）来动态决定要包含哪些补丁。

如果配置了较为宽泛的现代浏览器规则（例如 defaults、last 2 versions 或未指明兼容极低版本系统），Babel 经过计算认为你指定的所有目标浏览器都已原生支持 ES2015 Promise，因此即便你在配置里写了 useBuiltIns，Babel 也会在编译阶段把 Promise Polyfill 自动剔除。

npx browserslist

module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        // 指定支持的老旧环境，强制 Babel 识别 Promise 的缺失
        targets: {
          browsers: [
            '> 0.5%',
            'last 2 versions',
            'Firefox ESR',
            'not dead',
            'ie >= 11',
            'Android >= 4.4',
            'iOS >= 9'
          ]
        },
        useBuiltIns: 'entry', // 或 'usage'
        corejs: { version: 3, proposals: true }
      }
    ]
  ]
};

三、原因二：误将 transform-runtime 当作全局 Polyfill

许多项目在配置 Babel 时同时安装了 @babel/plugin-transform-runtime，并将其 corejs 选项开启。这里存在一个非常关键的机制差异：

@babel/plugin-transform-runtime 的设计初衷是避免污染全局环境，主要面向公共 npm 模块或 SDK 的开发者。当它处理业务代码中的 new Promise(...) 时，会将其静态替换为一个从 core-js-pure 导出的局部变量（如 var _Promise = require(...)），它绝对不会向宿主浏览器的 window.Promise 挂载任何东西。

如果你的应用引入了任何第三方依赖库（比如未经过二次 Babel 转译的图表库、请求库或 SDK），这些第三方库在执行时会直接寻址全局变量 Promise 或 window.Promise。由于全局环境完全没有被 polyfill，就会立刻抛出 Promise is not defined。

// 适合业务项目的标准插件配置
plugins: [
  [
    '@babel/plugin-transform-runtime',
    {
      corejs: false, // 业务项目不要开启局部 core-js 沙箱，交给全局 polyfill
      helpers: true,
      regenerator: true
    }
  ]
]

四、原因三：模块打包顺序与运行时执行时序滞后

即使产物中有 Polyfill，且也配置了全局挂载，如果执行时机不对，依然会报错。典型的时序陷阱表现为：

• 在项目入口文件 index.js 中，代码首行写了 import 'core-js/stable';。
• 第二行写了 import App from './App'; 或引入了某个第三方依赖 import 'some-legacy-sdk';。
• 在 JavaScript 模块规范中，子模块的执行会递归深入。部分打包器或特定的懒加载分包配置下，第三方包内顶层执行了立即调用表达式（IIFE），使用了 Promise。
• 在 HTML 模板层面，如果是以 <script> 标签分块加载，放置了业务脚本的 chunk 带有 defer 或 async，导致 polyfill chunk 尚未解析完成就执行了业务脚本。

为了彻底杜绝执行时序上的竞争，最佳工程实践是在构建工具的打包入口配置中强制前置 Polyfill：

// webpack.config.js
module.exports = {
  // 将 core-js 独立作为 entry 数组的第一个元素，强制打包在 bundle 最顶层
  entry: [
    'core-js/actual/promise', // 专门把 Promise 放在最前
    'core-js/stable',         // 补充其余基础补丁
    'regenerator-runtime/runtime',
    './src/main.js'           // 业务主代码
  ],
  output: {
    filename: '[name].[contenthash].js',
    path: path.resolve(__dirname, 'dist')
  }
};

五、原因四：core-js 3 路径破坏性变更与语法误写

core-js 在从版本 2 升级到版本 3 时，包内部结构发生了彻底的破坏性重构（Breaking Change）。许多教程和旧项目依然沿用版本 2 的导入语法：

如果你的 package.json 安装的是 core-js@^3.x.x，但代码中仍然书写 import 'core-js/es6/promise';，在某些旧版打包解析机制下可能静默跳过或解析为空文件，导致补丁根本没有生效。

// vite.config.js
import legacy from '@vitejs/plugin-legacy';

export default {
  plugins: [
    legacy({
      targets: ['ie >= 11', 'chrome >= 49', 'iOS >= 9'],
      additionalLegacyPolyfills: ['regenerator-runtime/runtime', 'core-js/actual/promise']
    })
  ]
};

六、验证修复与工程排查核对清单

完成上述调整后，如何确认问题已经彻底解决，而不是在当前机器上看起来正常？

可以通过以下两步严格验证：

1. 本地模拟极简低版本环境：在 Chrome 控制台或入口脚本最顶部添加一行模拟测试语句 delete window.Promise;，刷新页面，观察页面是否仍然能正常加载并显示。如果被成功 Polyfill，typeof window.Promise 在脚本执行后应当重新恢复为 'function'。
2. 使用真机或远程调试：在目标老旧手机 WebView 或 IE11 虚拟机中打开页面，在控制台直接输入 window.Promise.toString()，如果返回的是包含 Polyfill 内部特征的代码字符串（例如包含 [native code] 以外的封装逻辑），证明补丁已成功生效并接管全局。

总结来说，解决“引入了 core-js 仍报 Promise is not defined”的关键就在于：确保补丁被编译打入产物、保证补丁抢先在代码前执行、采用全局挂载而非局部别名、使用 core-js 3 规范路径。按照以上四个关键点依次核对，即可彻底根除任何老旧环境中的 Promise 缺失报错。