本文档为 Vue3+Vite 项目必备配置精简版，仅保留核心代码与关键说明，可直接复制使用，解决开发中端口冲突、跨域、路径冗长三大核心问题。
核心价值：一键复制即用，覆盖 90% 开发场景的基础配置需求。
📌 一、基础前提
配置文件：项目根目录下的 vite.config.js（与 package.json 同级）；
重要提醒：修改配置后必须重启项目（Ctrl+C 停止后重新 npm run dev），否则不生效。
配置文件：项目根目录下的 vite.config.js（与 package.json 同级）；修改后需重启项目（Ctrl+C 停止后重新 npm run dev）生效。
⚙️ 二、三合一核心配置（直接复制使用）
提示：仅需根据实际情况修改 target 后的后端地址，其余配置无需改动。
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue' // 支持Vue单文件组件
import path from 'path' // 内置路径模块，无需额外安装
export default defineConfig({
plugins: [vue()], // 固定注册Vue插件
// 1. 路径别名：@替代src目录，简化导入
resolve: {
alias: {
'@': path.resolve(__dirname, './src'), // 核心别名（必配）
'@components': path.resolve(__dirname, './src/components'), // 可选扩展
'@api': path.resolve(__dirname, './src/api') // 可选扩展
}
},
// 2. 端口配置 + 3. 跨域代理
server: {
port: 5174, // 自定义前端端口（避开占用，默认5173）
strictPort: true, // 端口占用直接报错（推荐开启）
open: true, // 启动后自动打开浏览器（推荐开启）
// 跨域代理（解决前端请求后端接口跨域问题）
proxy: {
'/api': { // 所有/api前缀请求均转发
target: 'http://localhost:3000', // 后端接口根地址（必改为你的后端地址）
changeOrigin: true, // 跨域核心开关（必须为true）
rewrite: (path) => path.replace(/^/api/, '') // 去掉/api前缀（按需配置）
}
}
}
})
📝 三、各配置核心说明
🔗 1. 路径别名（resolve.alias）
- 核心作用：用简短别名替代冗长路径，避免
../../层级混乱，提升开发效率。 - 使用示例：
import TodoItem from '@/components/TodoItem.vue'（替代多层级相对路径）。
🔌 2. 端口配置（server）
- 核心作用：解决端口占用报错，自定义前端访问地址（如
http://localhost:5174）。 - 关键参数：
port设为未被占用的数字即可，strictPort: true确保端口唯一性，避免自动切换导致地址混乱。
🔄 3. 跨域代理（server.proxy）
核心重点：跨域代理是开发环境必备配置，无此配置会导致接口请求阻塞。
- 核心作用：绕过浏览器同源策略，解决前端请求后端接口的跨域报错。
- 使用示例：前端请求
/api/todolist，自动转发为后端真实接口http://localhost:3000/todolist。 - 注意事项：
target需改为你的后端实际地址；若后端接口本身带/api前缀，删除rewrite配置，否则会导致接口 404。
⚠️ 四、关键注意事项
- 配置生效：修改后必须重启项目，Vite 不热更新配置文件，这是最易踩坑点。
- 环境限制：跨域代理仅在开发环境（
npm run dev）生效，生产环境需后端配置 CORS 允许跨域。 - 路径规范：路径别名中
@后需加/（如@/api），扩展别名（如@api）可直接使用，无需加斜杠。
