Mac升级Big Sur后使用asdf安装Yarn出现OpenSSL SSL连接错误

问题诱因 #

• 升级Big Sur系统后，之前手动配置的OpenSSL路径被系统重置，默认回到系统自带的旧版OpenSSL
• 旧版OpenSSL不支持Yarn官方源启用的TLS 1.2/1.3握手协议，SSL握手阶段无法识别服务器返回的协议信息，触发SSL23_GET_SERVER_HELLO:unknown protocol报错
• asdf的Yarn插件默认调用系统原生的curl/wget工具，这些工具如果绑定了旧版OpenSSL，就会出现连接失败问题
• 部分网络代理配置冲突，会篡改443端口的SSL流量，也会导致握手失败

排查解决步骤 #

1. 升级并配置新版OpenSSL #

首先通过Homebrew安装最新版OpenSSL：
brew install openssl@3
安装完成后打开Shell配置文件（zsh对应~/.zshrc，bash对应~/.bash_profile），添加以下配置将新版OpenSSL设为优先调用：

export PATH="/usr/local/opt/openssl@3/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/openssl@3/lib"
export CPPFLAGS="-I/usr/local/opt/openssl@3/include"

保存后执行source ~/.zshrc（对应bash替换为自己的配置文件名）生效，执行openssl version确认输出为3.x版本即配置成功。

2. 更新工具链与asdf插件 #

首先升级asdf的Yarn插件到最新版本：
asdf plugin update yarn
再通过Homebrew安装新版curl和wget，替代系统原生版本：
brew install curl wget
同样在Shell配置文件中添加配置优先调用新版curl：
export PATH="/usr/local/opt/curl/bin:$PATH"
生效后执行curl --version，确认输出中关联的OpenSSL版本为3.x即可。

3. 应急临时解决方案 #

如果上述步骤无法立刻解决问题，可以临时跳过SSL校验执行安装，该方法存在安全风险，仅推荐临时使用：
ASDF_YARN_SKIP_VERIFY=1 asdf install yarn 1.22.17
安装完成后无需额外配置，后续安装其他版本时建议恢复正常校验规则。 #

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