Ubuntu部署Node.js TS应用监听3000端口报EPERM错误求解

这类报错属于系统权限层拦截，和业务代码本身逻辑无关，你遇到的「极简原生HTTP脚本可正常运行、编译后的TS应用必报EPERM」的反常现象，完全可以通过以下步骤按优先级定位解决：

优先级排查步骤 #

• 第一步：核对两次运行的用户身份差异
  很多场景下测试极简脚本时是用 root 身份执行，部署TS应用时切换到普通业务用户（如www-data、专用node运行用户），两者权限基线不一致就会出现一个能跑、一个报错的情况。
  执行whoami确认触发报错时的当前运行身份，给当前环境的Node可执行文件绑定非特权端口绑定能力：sudo setcap 'cap_net_bind_service=+ep' $(readlink -f $(which node))——注意部分定制化Ubuntu镜像会扩大特权端口管控范围，即使是3000这类高于1024的端口，普通用户绑定也需要对应的capability权限。
• 第二步：排查AppArmor安全模块的静默拦截
  Ubuntu默认开启的AppArmor安全模块，会对非系统标准路径的Node进程、自定义项目目录下的可执行脚本的端口绑定行为做静默拦截，这类拦截不会在常规端口占用查询中显示，只会直接抛出EPERM错误。
  临时验证方法：执行sudo aa-status查看已加载的AppArmor规则，定位和Node进程相关的规则条目，临时禁用对应规则后重启服务，如果报错消失，将你的Node安装路径、项目运行目录加入AppArmor白名单即可，不要全局关闭安全模块。
• 第三步：排查系统防火墙/端口预留规则的限制
  不要仅通过lsof -i:3000判断端口状态，若Ubuntu的防火墙（ufw/iptables/firewalld）将3000端口设置为仅允许指定进程绑定，就算没有用户态进程实际占用该端口，非授权进程绑定也会触发EPERM。
  执行ss -tulnp | grep :3000、iptables -L -n | grep 3000确认3000端口是否存在绑定权限限制。
• 第四步：修正隐式监听地址的配置异常
  部分Node 16以上版本、以及Koa/Express这类Web框架，在未显式指定监听host的场景下，会优先尝试解析IPv6回环地址做监听；如果当前系统关闭了IPv6回环配置，就会触发EPERM。可以将监听逻辑调整为显式绑定所有网卡地址，比如把原有listen调用修改为：

  app.listen(3000, '0.0.0.0', function () {
    console.log('Listening on port 3000');
  });
  

反常现象的本质原因 #

你遇到的两类代码运行结果不一致，核心都是配置差异导致的，没有特殊逻辑：

• 两次运行使用的Node可执行文件不是同一个：测试脚本用系统全局安装的Node，TS应用用项目本地node_modules/.bin下的Node版本，后者没有对应的权限配置，自然会被系统拦截
• 两次运行的用户身份不一致：测试时用root拥有全部权限，部署应用时用无权限的普通用户
• 两类代码的默认监听逻辑不同：Web框架默认优先尝试IPv6地址绑定，原生极简脚本默认绑定IPv4全地址，前者更容易触发IPv6配置异常导致的EPERM

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