Ember-Auto-Import 2.0 升级指南：关键变更与技术解析

前言

Ember-Auto-Import 作为 Ember 生态中重要的依赖管理工具，在 2.0 版本中带来了多项重大改进。本文将深入解析这些变更，帮助开发者顺利完成升级。

核心变更概览

1. Webpack 从 v4 升级到 v5
2. 应用需要显式声明 Webpack 依赖
3. 内置 CSS 处理支持
4. 构建输出结构调整
5. 资产路径配置优化
6. 最低支持版本要求提升

详细技术解析

Webpack 5 升级影响

Webpack 5 带来了显著的性能提升和架构改进，但同时也引入了一些不兼容变更：

• Node 核心模块自动填充移除：Ember-Auto-Import 1.x 已默认禁用此功能，因此大多数应用不受影响
• 配置兼容性：大部分 Webpack 4 配置仍可在 5 中工作，但自定义配置需要验证
• 构建缓存改进：Webpack 5 的持久缓存机制可显著提升构建速度

最佳实践：检查项目中所有自定义 Webpack 配置，特别是涉及 Node 核心模块引用的部分。

显式 Webpack 依赖管理

2.0 版本要求应用显式声明 Webpack 依赖：

yarn add --dev webpack@5
# 或
npm install --save-dev webpack@5

架构意义：

• 应用获得对 Webpack 版本的控制权
• 可直接导入 Webpack 提供的插件和工具
• 避免依赖冲突

注意：插件不应将 Webpack 声明为 dependencies，而应放在 devDependencies 中。

CSS 处理内置支持

为兼容 Embroider v2 包规范，2.0 版本默认包含：

• css-loader
• style-loader
• MiniCSSExtraPlugin

升级影响：

• 需要移除手动添加的这些 loader 配置
• 确保样式导入路径正确

构建输出结构调整

2.0 版本改变了资源注入方式：

• 旧方式：将入口块附加到 vendor.js
• 新方式：直接在 index.html 中插入 script/link 标签

优势：

• 改善源映射支持
• 提升构建性能
• 优化缓存策略
• 解决某些 super 调用问题

部署注意：确保部署脚本包含 dist 目录下所有文件，而不仅是传统的 app.js 和 vendor.js。

资产路径配置

使用 CDN 时，需要同时配置 fingerprint 和 autoImport：

let app = new EmberApp(defaults, {
  fingerprint: {
    enabled: EmberApp.env() === 'production',
    prepend: 'http://some-cdn/xyz',
  },
  autoImport: {
    publicAssetURL: EmberApp.env() === 'production' 
      ? 'https://some-cdn/xyz/assets' 
      : undefined,
  },
});

关键点：publicAssetURL 需要包含 /assets 后缀。

版本兼容性要求

2.0 版本提升了最低支持版本：

• Node.js ≥ 12
• ember-source ≥ 3.4
• ember-cli ≥ 3.4
• Babel ≥ 7（移除 Babel 6 支持）

插件开发者注意事项

版本兼容策略

• 插件升级到 ember-auto-import ≥ 2.0 需要做主版本号升级
• 依赖链中的插件需要递归升级
• 应用必须使用 ember-auto-import ≥ 2.0

自定义 Webpack 配置

虽然大多数 1.x 的自定义配置在 2.0 中仍能工作，但建议：

1. 优先使用 ember-auto-import 提供的声明式 API
2. 修复上游库的构建问题
3. 如必须使用自定义配置，需明确声明支持的版本范围

Alias 选项变更

2.0 版本调整了 alias 的匹配规则：

• 1.x：仅精确匹配
• 2.0：默认前缀匹配，可使用 $ 表示精确匹配

这与 Webpack 原生 alias 行为保持一致，提高了配置的可预测性。

升级检查清单

1. 检查并更新 Webpack 自定义配置
2. 添加 Webpack 5 依赖
3. 移除手动添加的 CSS 相关 loader
4. 验证部署脚本是否处理所有 dist 文件
5. 如需 CDN，配置 publicAssetURL
6. 更新 CI 环境中的 Node.js 版本
7. 检查依赖插件是否兼容 2.0

结语

Ember-Auto-Import 2.0 的变更为 Embroider 的全面采用铺平了道路，同时带来了更好的性能和开发体验。遵循本指南的推荐步骤，可以确保平稳过渡到新版本。