解决 Vite 项目启动时端口重复问题的总结

背景

在前端开发的江湖上，Vite 就像一个轻盈迅捷的剑客，以“快”和“爽”闻名。默认栖身于本地 3000 端口，简直是开发者的“专属包间”。但江湖人多，难免遇到这种情况：你刚起剑练招，发现隔壁的同门师兄已经占了你的包间。于是，你只能抱着代码，哼哼唧唧换个地方继续修炼——这种“被端口抢占”的故事，简直就是开发者的日常笑话！

例如：

1. 多人协作：团队中的多个开发者同时运行了 Vite 项目，使用了相同的端口。
2. 多项目运行：本地同时启动了多个 Vite 项目或其他服务（如 Webpack、Node.js 服务器），导致端口冲突。
3. 默认配置不足：Vite 默认没有处理端口占用的逻辑，遇到冲突会直接报错，开发中断。

为了解决这个问题，我研究了几种方法，最终采用了 detect-port 插件，实现了动态检测和自动调整端口的功能，极大地提升了开发效率。

---

解决方案

1. 常见解决方法

1.1 手动更改端口*

在 vite.config.ts 文件中修改 server.port 的值。例如：

export default defineConfig({
  server: {
    port: 3001, // 手动指定一个新的端口
  },
});

​ 缺点：需要手动调整端口，效率较低，且不方便多人协作。

1.2 尝试端口范围

一些开发者会通过运行脚本动态尝试多个端口，但编写脚本可能较繁琐且不直观。

1.3 使用第三方工具

利用工具如 detect-port 或 portfinder，自动检测端口是否被占用并返回可用端口。

2. Detect-port 的解决方案（本人的解决方法）

我最终采用了 detect-port 插件，因为它简单易用，能够自动检测当前端口是否被占用，并返回一个可用的端口。

Step 1: 安装 detect-port

在项目根目录下运行以下命令：

pnpm install detect-port --save-dev

或者使用 npm/yarn 安装：

npm install detect-port --save-dev
yarn add detect-port --dev

Step 2: 配置 Vite 项目

修改 vite.config.ts 文件，引入 detect-port，实现动态端口检测：

import { defineConfig } from 'vite';
import detectPort from 'detect-port';

export default defineConfig(async () => {
  const DEFAULT_PORT = 3000; // 默认端口

  // 使用 detect-port 检测端口是否被占用
  const port = await detectPort(DEFAULT_PORT);

  console.log(`Selected port: ${port}`); // 输出实际选用的端口

  return {
    server: {
      host: '0.0.0.0', // 允许局域网访问
      port, // 动态端口
      open: true, // 自动打开浏览器
      proxy: {
        '/api': {
          target: 'http://localhost:5000',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, ''),
        },
      },
    },
  };
});

Step 3: 效果展示

• 如果默认端口（如 3000）已被占用，detect-port 会自动检测下一个可用端口，例如 3001 或 3002。
• 启动时会输出实际使用的端口号：

Selected port: 3001

这样，我们无需手动修改端口设置，提升了开发效率。lalala~

3. 优化点

在实践中，我还添加了一些优化：

3.1 添加日志输出

使用 console.log 记录端口信息，便于调试：

console.log(`Using port ${port}. To change, edit vite.config.ts`);

3.2 范围检测（可选）

通过扩展 detect-port，可尝试在特定范围内寻找端口：

const port = await detectPort(3000);
if (port !== 3000) {
  console.log(`Port 3000 is in use. Using port ${port} instead.`);
}

小结

问题总结

Vite 默认端口冲突的问题在多人协作和多项目运行的场景中非常常见。传统的手动解决方案需要频繁调整配置，显得麻烦且低效。

我的解决方案

利用 detect-port 插件，可以轻松实现动态端口检测和分配：

• 自动检测端口冲突。
• 动态分配可用端口，提升开发效率。
• 配置简单、易于扩展。

未来优化

• 扩展端口范围检测：可以尝试自定义检测端口范围（如 3000-3100）。
• 集成其他工具：例如结合 vite-plugin-inspect，提供更多启动信息。
• 多环境支持：为不同环境（开发、测试、生产）定制端口策略。

在团队开发中，这种自动化的方式能够显著减少端口冲突问题，提升协作效率，非常值得推广。