执行serverless offline start启动Node.js Lambda报EISDIR错误如何解决

问题场景 #

Node.js技术栈开发Lambda函数时，执行serverless offline start启动本地调试环境触发运行错误，连续排查2天未定位根因。

核心报错 #

Error: EISDIR: illegal operation on a directory, symlink 'R:Projects<project>\node_modules' -> 'R:Projects<project>.build\node_modules'

报错根因 #

该错误触发于Serverless Offline生成临时构建目录.build的环节，框架尝试为项目依赖目录node_modules创建软链接时操作失败，常见诱因包括：

• Windows环境下普通权限终端默认无目录软链接创建权限，系统直接拦截操作
• 之前异常退出的启动流程残留了损坏的.build目录，内部已存在同名node_modules目录，和新的软链接创建请求冲突
• Windows路径解析异常，报错信息中源路径R:Projects<project>缺失路径分隔符，框架拼接路径时未正确识别反斜杠，将目录误判为普通文件触发操作非法报错
• 配套构建插件（如serverless-esbuild）默认的软链接依赖逻辑和本地目录结构不兼容

修复步骤 #

按顺序操作，每步完成后重试启动命令验证是否修复：

• 强制删除项目根目录下残留的.build构建缓存目录，Windows PowerShell下执行：

  Remove-Item -Recurse -Force .\.build
  

• 以管理员身份重启终端，切换到项目目录后重新执行启动命令，排除权限拦截问题
• 若仍报错，修改项目根目录下serverless.yml配置，关闭node_modules软链接逻辑，强制复制依赖到构建目录，配置示例：

  custom:
    serverless-offline:
      symlinkNodeModules: false
  

• 将项目迁移到无中文、无特殊字符、无空格的纯英文短路径下（如R:\code\lambda-demo），规避路径分隔符解析丢失问题
• 若使用高版本serverless-offline出现该问题，可回退到已知稳定版本：

  npm uninstall serverless-offline
  npm install serverless-offline@12.0.4 --save-dev
  

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