Teable 开发模式修改后端代码不生效、3000 端口被占用怎么排查？

Teable 开发模式修改后端代码不生效、3000 端口被占用怎么排查？

【免费下载链接】teable✨ AI Spreadsheet for Business项目地址: https://gitcode.com/GitHub_Trending/te/teable

在 Teable 仓库里以开发模式跑起来之后（apps/nestjs-backend下执行pnpm dev），有两个容易同时出现的现象：改完后端代码刷新页面却不生效，以及 3000 端口被残留进程占用导致重启失败。Teable 的 CONTRIBUTING.md 在 Known Issues 一节把这两个现象归为同一类问题：开发模式下的热重载重启引发的端口冲突，并给出了用lsof -i:3000定位、kill -9清理、再pnpm dev重启的处理路径。这篇文章按文档给出的流程走一遍，先交代开发模式的端口分配，再给出完整的检查与恢复步骤。适用环境：Linux/Mac（Windows 需使用 WSL2），PostgreSQL 开发库依赖 Docker。

为什么会出现这两个现象：开发模式的端口分配

先看 Teable 开发模式里各端口被谁占用，这是理解问题前提，配置来源是 apps/nextjs-app/.env.development：

• PORT=3000：后端（NestJS）HTTP 服务端口；
• SOCKET_PORT=3001：应用自身的 websocket 端口；
• PUBLIC_ORIGIN=http://localhost:3000。

按 CONTRIBUTING.md 的说明，开发模式下 Next.js 会占用 3000 端口的 websocket 通道来触发热重载，为了避免冲突，应用的 websocket 挪到了 3001，所以你会在.env.development.local里看到SOCKET_PORT=3001。而生产环境默认用 3000 端口处理 websocket 请求。

冲突的触发条件文档也写清楚了：开发模式下代码改动会触发热重载，如果改动影响到apps/nestjs-backend（包括packages/core、packages/db-main-prisma），nodejs 进程可能重启，重启过程中就可能留下端口冲突。表现就是后端代码改动看起来没有生效，此时 3000 端口大概率还被旧进程占着。

准备：按文档方式启动开发环境

如果还没跑起来，按 CONTRIBUTING.md（与 README.md 的 Development 一节一致）初始化：

# 启用包管理器 corepack enable # 安装依赖 pnpm install

Teable 开发使用 PostgreSQL，且要求已安装 Docker。初始化数据库用：

make switch-db-mode

这一步会交互式询问选择哪种数据库（1) postgres(pg)），选择1即可；它对应 Makefile 中的switch-db-mode目标，会启动 postgres 容器、等待 healthy 后执行 prisma 的 generate 与 migrate deploy。

可选的环境配置覆盖，用于需要自定义变量时：

cd apps/nextjs-app cp .env.development .env.development.local

最后启动开发服务：

cd apps/nestjs-backend pnpm dev

这条命令会自动把后端和前端服务器一起启动并开启热重载。pnpm dev背后是 apps/nestjs-backend/package.json 里的nest start --webpackPath ./webpack.dev.js -w，即 webpack watch 模式，文件变化自动重载。

修改后端代码不生效时：检查 3000 端口

按文档给出的排查顺序，当后端代码改动看似没有生效时，先确认端口是否被占用：

lsof -i:3000

判断方式：输出中出现监听 3000 端口的进程（通常是上一个没退干净的 node 进程），就说明是文档描述的端口冲突，继续下一步清理；如果没有任何进程占用 3000，则不属于文档覆盖的这个已知问题，需要另行排查（文档未给出其他情形的处理）。

释放端口并重启开发服务

清理命令会强制终止进程，执行前确认[pid]就是上一步lsof -i:3000输出中占用 3000 端口的进程 PID，不要对无关进程执行：

kill -9 [pid] # [pid] 替换为 lsof 输出中的进程 PID

然后回到后端目录重新启动：

cd apps/nestjs-backend pnpm dev

文档给出的恢复路径到此结束：旧进程被清理、开发服务以热重载重新跑起来后，后续对apps/nestjs-backend的改动即可正常热更新。

限制与注意事项

• SOCKET_PORT=3001是开发模式的设计值，不是配置错误，不要把它改回 3000；生产环境默认使用 3000 处理 websocket 请求，两者行为不同。
• 热重载端口冲突主要出现在改动影响apps/nestjs-backend（packages/core、packages/db-main-prisma）的场景，这是文档点名的触发范围。
• 拉取最新代码后的常规维护，文档建议在pnpm install之后再执行一次make switch-db-mode，保持依赖与数据库 schema 同步；如果你刚改过 schema，还涉及make gen-prisma-schema、make db-migration等迁移流程，超出本文排查范围，详见 CONTRIBUTING.md 的 Database Migration Workflow 一节。

【免费下载链接】teable✨ AI Spreadsheet for Business项目地址: https://gitcode.com/GitHub_Trending/te/teable