Flutter应用iOS端运行时出现CocoaPods报错如何排查

问题表现 #

• GitHub克隆的Flutter项目Android端可正常运行，iOS端debug模式启动到Running pod install...阶段直接报错
• 核心报错信息：

  WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.
  Unicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError)

• 最终抛出Error running pod install，无法在iPhone SE（第三代）模拟器上启动应用

故障原因 #

• 终端环境未配置UTF-8编码，CocoaPods依赖的系统Ruby 2.6在处理路径字符串时触发编码兼容异常，无法正常读取Podfile完成依赖安装
• 部分场景下项目路径包含中文/特殊字符、CocoaPods版本混用也会触发同类报错

修复步骤 #

1. 配置终端UTF-8环境变量
   根据你使用的shell类型，编辑对应配置文件：
   • 默认zsh（MacOS 10.15及以上版本默认）：编辑~/.zshrc
   • bash shell：编辑~/.profile或~/.bash_profile
     在文件末尾添加两行配置：

   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8
   

   保存后执行source 配置文件路径让配置立即生效，例如zsh环境执行source ~/.zshrc
2. 清理旧缓存重新安装依赖
   进入项目根目录下的ios文件夹，依次执行命令：

   rm -rf Pods Podfile.lock
   pod cache clean --all
   pod install
   

3. 兜底排查（上述步骤无效时操作）
   • 检查项目存放路径是否包含中文、空格或特殊字符，若有则移动到纯英文路径下重试
   • M系列芯片Mac可给终端开启Rosetta权限后重新执行pod安装，避免架构兼容问题
   • 不要混用系统gem安装的CocoaPods和Homebrew安装的CocoaPods，保留一个安装源即可

内容的提问来源于stack exchange，提问作者Fuad Azmi