新MacBook运行SPFx项目执行gulp serve触发SPrintFImpl断言失败求助

问题背景 #

旧MacBook上开发SPFx项目完全正常，更换新MacBook后从ADO仓库克隆项目，安装了和旧机器完全一致的依赖版本：Node 16.13.2、Gulp-cli 2.3.0、本地Gulp 4.0.2、Python 2.7.18、Python3 3.10.9。node_modules已成功安装，但执行任何Gulp命令都会触发断言失败错误。

错误日志 #

gulp serve[48685]: ../src/debug_utils-inl.h:67:std::string node::SPrintFImpl(const char *): Assertion `(p[1]) == ('%')' failed.
1: 0x1058bbee5 node::Abort() (.cold.1) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
2: 0x104571dc9 node::Abort() [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
3: 0x104571c31 node::Assert(node::AssertionInfo const&) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
4: 0x1044a49a5 node::SPrintFImpl(char const*) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
5: 0x1058b9602 std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> node::SPrintF<>(char const*) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
6: 0x104547ebd v8::Local<v8::Value> node::ERR_DLOPEN_FAILED<>(v8::Isolate*, char const*) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
7: 0x104547b50 std::__1::__function::__func<node::binding::DLOpen(v8::FunctionCallbackInfo<v8::Value> const&)::$0, std::__1::allocator<node::binding::DLOpen(v8::FunctionCallbackInfo<v8::Value> const&)::$0>, bool (node::binding::DLib*)>::operator()(node::binding::DLib*&&) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
8: 0x104546700 node::Environment::TryLoadAddon(char const*, int, std::__1::function<bool (node::binding::DLib*)> const&) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
9: 0x104546503 node::binding::DLOpen(v8::FunctionCallbackInfo<v8::Value> const&) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
10: 0x104762ae5 v8::internal::FunctionCallbackArguments::Call(v8::internal::CallHandlerInfo) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
11: 0x1047620b8 v8::internal::MaybeHandle<v8::internal::Object> v8::internal::(anonymous namespace)::HandleApiCallHelper<false>(v8::internal::Isolate*, v8::internal::Handle<v8::internal::HeapObject>, v8::internal::Handle<v8::internal::HeapObject>, v8::internal::Handle<v8::internal::FunctionTemplateInfo>, v8::internal::Handle<v8::internal::Object>, v8::internal::BuiltinArguments) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
12: 0x10476167f v8::internal::Builtin_Impl_HandleApiCall(v8::internal::BuiltinArguments, v8::internal::Isolate*) [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
13: 0x104ff0a19 Builtins_CEntry_Return1_DontSaveFPRegs_ArgvOnStack_BuiltinExit [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
14: 0x104f8b445 Builtins_InterpreterEntryTrampoline [/Users/myusername/.nvm/versions/node/v16.0.0/bin/node]
zsh: abort      gulp serve

解决方案 #

1. 修复Node版本不一致问题 #

从错误日志路径可见，当前实际使用的是Node v16.0.0，而非你安装的v16.13.2，这是核心诱因：

• 执行node -v和nvm list确认版本状态
• 切换到指定版本：nvm use 16.13.2
• 设置为默认版本：nvm alias default 16.13.2
• 重启终端后再次验证版本是否正确

2. 清理并重装依赖 #

版本不匹配可能导致依赖编译异常，执行以下步骤：

• 删除本地依赖和锁文件：rm -rf node_modules package-lock.json yarn.lock
• 重新安装依赖：npm install
• 若安装时出现编译错误，关联正确Python版本：

  npm config set python /usr/bin/python2.7
  npm config set python3 /usr/bin/python3.10
  

3. 验证Gulp版本匹配度 #

确认全局与本地Gulp版本一致：

• 执行gulp -v，输出应显示CLI版本2.3.0、本地版本4.0.2
• 若版本不符，重新安装指定版本：

  npm uninstall -g gulp-cli
  npm install -g gulp-cli@2.3.0
  npm uninstall gulp
  npm install gulp@4.0.2 --save-dev
  

4. 适配M系列芯片架构 #

新MacBook若为ARM架构（M系列）：

• 右键终端→获取信息→勾选"使用Rosetta打开"，以兼容部分x86原生模块
• 重新执行依赖安装和Gulp命令

5. 重置NVM环境 #

若版本切换仍有异常：

nvm cache clear
nvm uninstall 16.0.0
nvm install 16.13.2

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