修改 Vite 应用端口

问题描述

在使用 Vite 开发或预览应用时，默认端口通常为 5173（开发服务器）或 4173（预览服务器）。但在实际开发中，您可能需要修改这些端口，例如：

• 端口 5173 已被其他应用占用
• 需要同时运行多个 Vite 项目
• 遵守特定项目的端口规范要求
• 与后端 API 运行在同一端口域下

解决方案

Vite 提供了多种方式来修改应用端口，以下是几种常用方法：

方法一：通过 Vite 配置文件修改（推荐）

在 vite.config.ts 或 vite.config.js 中配置端口：

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 3000, // 开发服务器端口
  },
  preview: {
    port: 3001, // 预览服务器端口
  }
})

提示

通过这种方式可以为开发和预览环境分别设置不同的端口，便于区分环境

方法二：在 package.json 中修改

在 package.json 文件的 scripts 部分直接指定端口：

{
  "scripts": {
    "dev": "vite --port 3006",
    "build": "vite build",
    "preview": "vite preview --port 3007"
  }
}

方法三：通过命令行参数临时修改

在运行命令时直接通过 --port 参数指定端口：

# 开发时指定端口
npm run dev -- --port 3000
yarn dev --port 3000
pnpm dev --port 3000

# 预览时指定端口
npm run preview -- --port 3001
yarn preview --port 3001
pnpm preview --port 3001

注意

使用命令行参数时，需要在脚本名称后添加额外的 -- 来传递参数给 Vite

方法四：通过环境变量配置

使用 .env 文件和环境变量来配置端口：

1. 创建或编辑 .env 文件：

   VITE_PORT=3000

2. 在 vite.config.ts 中读取环境变量：

   import { defineConfig, loadEnv } from 'vite'
   
   export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'VITE_')
     
     const port = Number(env.VITE_PORT) || 3000
     
     return {
       server: {
         port: port,
         strictPort: true, // 如果端口被占用则直接失败
       },
       preview: {
         port: port,
         strictPort: true,
       }
     }
   })

环境变量前缀

Vite 只会暴露以 VITE_ 开头的环境变量给客户端代码，这是默认的安全限制

配置详解

strictPort 选项

当设置 strictPort: true 时，如果指定的端口已被占用，Vite 会直接失败而不是自动尝试其他端口：

server: {
  port: 3000,
  strictPort: true, // 端口占用时报错，而非自动切换
}

host 配置

除了端口，您还可以配置服务器主机：

server: {
  port: 3000,
  host: true, // 监听所有地址
  // 或指定特定主机
  // host: '0.0.0.0'
}

常见问题

端口被占用怎么办？

如果遇到端口被占用的情况，可以：

1. 尝试使用不同的端口号
2. 关闭占用端口的其他进程
3. 使用 strictPort: false 让 Vite 自动寻找可用端口

配置不生效？

请确保：

• 配置文件路径正确（通常是项目根目录下的 vite.config.ts）
• 配置文件语法正确，没有错误
• 重启开发服务器使配置生效

最佳实践

1. 开发和预览使用不同端口：便于区分环境
2. 使用环境变量：便于在不同环境（开发、测试、生产）中使用不同配置
3. 文档化端口配置：在项目文档中记录使用的端口，方便团队协作

总结

修改 Vite 应用端口有多种方法，推荐使用配置文件方式，因为它提供了最好的灵活性和可维护性。对于团队项目，建议结合环境变量使用，以便在不同环境中轻松切换配置。