tianshu-engine/docs/electron-port-finder.md

Electron 端口自动查找功能

功能说明

Electron 应用启动时会自动在 9527-9999 端口范围内寻找可用端口，避免端口冲突问题。

工作原理

1. 端口检测

使用 Node.js 内置的 net 模块检测端口是否可用：

function isPortAvailable(port) {
  return new Promise((resolve) => {
    const server = net.createServer()
    server.listen(port, '127.0.0.1', () => {
      server.once('close', () => resolve(true))
      server.close()
    })
    server.on('error', () => resolve(false))
  })
}

2. 端口查找

从 9527 开始向上查找，直到找到可用端口：

async function findAvailablePort(startPort, maxPort) {
  for (let port = startPort; port <= maxPort; port++) {
    const available = await isPortAvailable(port)
    if (available) {
      return port
    }
  }
  throw new Error(`No available port found between ${startPort} and ${maxPort}`)
}

3. 服务器启动

找到可用端口后启动 Express 服务器：

const serverInfo = await startServer()
const { server, PORT } = serverInfo

配置参数

参数	默认值	说明
START_PORT	9527	起始端口
MAX_PORT	9999	最大端口

使用示例

正常情况

✅ Local server running at http://127.0.0.1:9527
🚀 Loading app from: http://127.0.0.1:9527/index.html

端口冲突情况

🔒 Port 9527 is blocked
✅ Local server running at http://127.0.0.1:9528
🚀 Loading app from: http://127.0.0.1:9528/index.html

优势

1. 自动处理冲突 - 无需手动指定端口
2. 范围可控 - 限制在 9527-9999 范围内
3. 快速响应 - 端口检测速度快
4. 零依赖 - 使用 Node.js 内置模块

注意事项

1. 端口范围 - 如果 9527-9999 都被占用，会抛出错误
2. 监听地址 - 只监听 127.0.0.1，不暴露到外网
3. 服务器关闭 - 应用退出时会自动关闭服务器

测试

测试端口查找

node scripts/test-port-finder.cjs

测试端口冲突

node scripts/test-port-conflict.cjs

故障排查

端口范围耗尽

如果出现 "No available port found" 错误：

1. 检查是否有其他应用占用了大量端口
2. 增加 MAX_PORT 的值
3. 关闭不必要的应用释放端口

服务器启动失败

如果服务器启动失败：

1. 检查 dist 目录是否存在
2. 检查文件权限
3. 查看控制台错误信息