NextJS执行yarn dev触发Assertion `args[0]->IsInt32()'失败错误

问题场景 #

在NextJS本地开发环境执行yarn dev时，触发Node底层断言错误，错误输出如下：

/opt/homebrew/Cellar/node/19.9.0/bin/node[8717]: ../src/tcp_wrap.cc:155:static  void node::TCPWrap::New(const FunctionCallbackInfo<v8::Value> &): Assertion `args[0]->IsInt32()' failed.
[/opt/homebrew/Cellar/node/19.9.0/bin/node]
51: 0x1044f3d70 node::crypto::TLSWrap::Cycle() [/opt/homebrew/Cellar/node/19.9.0/bin/node]
52: 0x1044f229c node::crypto::TLSWrap::OnStreamRead(long, uv_buf_t const&) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
53: 0x10448a48c node::LibuvStreamWrap::OnUvRead(long, uv_buf_t const*) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
54: 0x10448a13c node::LibuvStreamWrap::ReadStart()::$_1::__invoke(uv_stream_s*, long, uv_buf_t const*) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
55: 0x106d32ff0 uv__stream_io [/opt/homebrew/Cellar/libuv/1.44.2/lib/libuv.1.dylib]
56: 0x106d3a1e0 uv__io_poll [/opt/homebrew/Cellar/libuv/1.44.2/lib/libuv.1.dylib]
57: 0x106d2a7bc uv_run [/opt/homebrew/Cellar/libuv/1.44.2/lib/libuv.1.dylib]
58: 0x1042fd8d8 node::SpinEventLoopInternal(node::Environment*) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
59: 0x1044025c0 node::NodeMainInstance::Run(node::ExitCode*, node::Environment*) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
60: 0x104402344 node::NodeMainInstance::Run() [/opt/homebrew/Cellar/node/19.9.0/bin/node]
61: 0x10438acf4 node::LoadSnapshotDataAndRun(node::SnapshotData const**, node::InitializationResultImpl const*) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
62: 0x10438ae90 node::Start(int, char**) [/opt/homebrew/Cellar/node/19.9.0/bin/node]
63: 0x18640fe50 start [/usr/lib/dyld]
error Command failed with signal "SIGABRT".

已尝试操作：

• 多次执行yarn install和yarn cache clean
• 检查并修改package.json
• 降级Node.js至14、16版本
• 恢复至之前可正常运行的代码分支

当前状态：yarn build生成的生产产物部署后可正常运行，问题仅出现在开发环境，判定与开发依赖相关。

针对性解决步骤 #

1. 清理NextJS开发缓存

NextJS开发环境有独立缓存目录，手动清理后重试：

rm -rf .next/cache

2. 锁定开发依赖版本

检查package.json中devDependencies，尤其是next、webpack-dev-server等与开发服务相关的包，将其版本锁定为项目之前能正常运行的具体版本，避免依赖自动升级引入兼容性问题。

3. 临时禁用Fast Refresh验证

在next.config.js中添加配置禁用Fast Refresh，排查是否是热重载机制触发的底层问题：

module.exports = {
  fastRefresh: false,
}

若禁用后问题消失，说明是Fast Refresh与当前环境的兼容性问题，可等待NextJS更新或切换稳定版本。

4. 排查本地网络工具冲突

暂时关闭本地代理工具（如Charles、Fiddler）或VPN，这类工具可能干扰Node的TCP/TLS流处理，触发底层断言错误。

5. 彻底重装依赖

删除node_modules和锁文件后，严格按照锁文件版本重新安装：

rm -rf node_modules yarn.lock
yarn install --frozen-lockfile

6. 切换Node.js LTS版本

Node 19为非LTS版本，可能存在未修复的底层bug，尝试切换到最新LTS版本（如18.x）后测试。

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