Vite 启动时如何指定自定义端口？

Question

**问题描述：** 在使用 Vite 构建前端项目时，默认的开发服务器端口为 `5173`。然而，在实际开发中，由于端口冲突或团队协作需求，常常需要修改为其他自定义端口。那么，如何在启动 Vite 时指定自定义端口？是否可以通过命令行参数或配置文件的方式实现？不同项目类型（如 Vue、React、纯 HTML/JS）是否存在差异？此外，当使用 `vite preview` 命令预览构建结果时，又该如何指定端口？了解这些方法有助于提升开发效率和部署灵活性。

Answer 1

一、Vite 默认端口与常见问题

Vite 是现代前端开发工具，以其快速冷启动和热更新能力广受开发者喜爱。默认情况下，Vite 的开发服务器运行在端口 5173。

然而，在实际项目中，可能会遇到以下问题：

• 本地其他服务占用了 5173 端口；
• 多个 Vite 项目同时运行时发生冲突；
• 团队协作中需要统一使用特定端口。

二、命令行方式指定端口

Vite 提供了简洁的 CLI 命令来修改开发服务器的端口：

npm run dev -- --port 3000

该命令会将开发服务器启动在 localhost:3000 上。

对于 vite preview 命令预览构建结果时，也可以通过如下方式指定端口：

vite preview --port 4000

此方法适用于所有项目类型（Vue、React、HTML/JS）。

三、配置文件方式设置端口

更持久的方式是通过 vite.config.js 文件进行配置：

export default defineConfig({
  server: {
    port: 8080
  }
});

这样每次执行 npm run dev 都会自动使用 8080 端口。

同样地，preview 模式也支持配置：

export default defineConfig({
  preview: {
    port: 9090
  }
});

这种配置方式具有更强的可维护性和一致性。

四、不同项目类型的兼容性分析

无论你使用的是 Vue、React 还是纯 HTML/JS 项目，Vite 的端口配置机制都是一致的。以下是不同类型项目的典型结构对比：

项目类型	是否支持 CLI 设置端口	是否支持 vite.config.js 设置端口	备注
Vue	✅	✅	基于 Vite 插件体系
React	✅	✅	同上
HTML/JS	✅	✅	原生支持

五、高级用法与自动化脚本

为了进一步提升效率，可以结合 shell 脚本或 npm scripts 自动化端口切换：

"scripts": {
  "dev": "vite",
  "dev:3000": "vite --port 3000",
  "preview:4000": "vite preview --port 4000"
}

此外，还可以通过 Node.js 脚本动态检测可用端口并启动服务，避免手动干预。

以下是一个简单的端口探测逻辑示例：

const { exec } = require('child_process');

function findAvailablePort(startPort, callback) {
  const cmd = `lsof -i :${startPort}`;
  exec(cmd, (error, stdout, stderr) => {
    if (!stdout) {
      callback(startPort);
    } else {
      findAvailablePort(startPort + 1, callback);
    }
  });
}

findAvailablePort(3000, (port) => {
  console.log(`Starting Vite on port ${port}`);
  // 启动 Vite 并传入 port 参数
});

六、流程图：端口配置决策路径

下面是一个 Mermaid 流程图，展示了如何根据需求选择不同的端口配置方式：

graph TD
      A[是否只需要临时更改端口？] -->|是| B[使用 CLI 命令]
      A -->|否| C[编辑 vite.config.js]
      D[是否需要预览模式？] -->|是| E[vite preview --port XX]
      D -->|否| F[使用 dev 模式]
      G[项目类型是否影响？] --> H[不影响，通用配置]