升级Angular14后@angular/forms无UntypedFormGroup导出报错

问题场景 #

• 企业级Angular应用原运行版本为Angular 13.3.8，升级至14.0.0版本后抛出报错：Module '"@angular/forms"' has no exported member 'UntypedFormGroup'
• 升级流程自动修改了组件代码：
  1. 从@angular/forms中自动添加了UntypedFormBuilder和UntypedFormGroup的导入
  2. 将原有表单组类型定义form: FormGroup;替换为form: UntypedFormGroup;
• 修改后运行触发第二个报错：Cannot find name 'UntypedFormBuilder'
• 验证结果：将部分自动转换的代码改回常规FormGroup后应用可正常运行，但逐文件手动回滚的工作量较大，且暂未查询到UntypedFormBuilder、UntypedFormGroup的使用价值，当前临时处理方式为将所有UntypedFormBuilder实例替换回FormBuilder实例。

报错根因 #

Angular 14正式上线了严格类型化表单（Typed Forms）特性，Untyped*系列表单类是官方为存量应用渐进式迁移预留的兼容层，出现导入报错的核心原因是升级流程执行不完整：

• 自动迁移脚本仅修改了代码中的类型引用与导入语句，但未完成@angular/forms包的版本同步校验，本地实际加载的forms包仍为13.x版本，不存在14版本才正式导出的Untyped*成员
• 部分项目存在依赖嵌套、锁文件未更新的问题，会进一步加剧@angular系列包的版本错位问题。

可落地的修复方案 #

根据项目后续迭代需求，二选一即可：

• 方案1：不启用严格类型表单，最低成本修复
  不需要逐文件手动修改，直接做两轮全局替换即可：
  1. 全局替换导入语句：将所有文件中从@angular/forms导入的UntypedFormBuilder/UntypedFormGroup/UntypedFormControl/UntypedFormArray，替换为对应的FormBuilder/FormGroup/FormControl/FormArray
  2. 全局替换类型声明：将代码中所有用到上述Untyped*类型的位置，替换为去掉Untyped前缀的原有表单类型
     替换完成后重新执行依赖安装、重启开发服务即可，修复后表单行为和Angular 13版本完全一致，无额外兼容成本。
• 方案2：修复迁移流程，保留渐进式升级能力
  如果后续计划逐步接入严格类型表单能力，可以按以下步骤修复：
  1. 删除项目下的node_modules目录和对应包管理器的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml）
  2. 重新执行依赖安装命令，确认所有@angular/*相关包的版本统一为14.0.0，无版本错位
  3. 手动执行官方类型表单迁移命令：ng generate @angular/core:typed-forms
     修复完成后Untyped*系列类型可正常导入使用，不影响当前业务运行，后续可按需逐个将无类型表单改造为严格类型表单。

Untyped*表单类的作用说明 #

不少开发者升级时会困惑这类类型的存在价值，这里做统一说明：

Angular 14之前的FormGroup/FormControl等类型默认是无类型的，表单值默认推导为any，不做编译期类型校验。14版本推出严格类型表单后，原生FormGroup等类型默认开启严格类型校验，而Untyped*系列类型的行为和13版本的旧表单类完全一致，属于官方提供的兼容层。它的核心作用是降低大版本升级成本：升级时自动把所有旧表单标记为Untyped类型保证应用可正常运行，开发者不需要一次性改完所有表单的类型定义，后续迭代中再逐步改造为严格类型表单即可。

内容的提问来源于stack exchange，提问作者Joshua Michael Calafell