uni-app怎么使用Vite uni-app Vue3版本构建工具配置【配置】-uni-app-PHP中文网

uni-app vue3 项目自 v3.9.0 起默认使用 vite 构建，无需手动切换；需确保 cli ≥ 3.9.0、使用 vue3 模板，配置应写在 vite.config.ts 中并调用 defineuniappconfig，环境变量须以 uni_app_ 或 vue_app_ 开头，且第三方插件需谨慎兼容。

uni-app怎么使用vite uni-app vue3版本构建工具配置【配置】

uni-app Vue3 项目默认就用 Vite，不用额外配置

uni-app 自 v3.9.0 起，新建的 Vue3 项目（vue3 + typescript 模板）底层构建工具就是 Vite，不是旧版的 Webpack。你执行 npm create uni-app@latest 选 Vue3，生成的项目里根本找不到 vue.config.js 或 webpack.config.js —— 因为它压根不走 Webpack 流程。

常见误解是“要手动把 uni-app 切到 Vite”，其实只要确认项目是 Vue3 模板、CLI 版本 ≥ 3.9.0，npm run dev 启动的就是 Vite 开发服务器。

检查 CLI 版本：npx uni-app -V，低于 3.9.0 就升级：npm install -g @dcloudio/vue-cli
老项目（Vue2 或旧 Vue3）升级需重开新项目，不支持原地迁移 Vite 构建链
vue.config.js 在 Vite 模式下完全失效，删掉也不会报错，但留着会误导人

自定义 Vite 配置要改 `vite.config.ts`，不是 `vue.config.js`

需要调整构建行为（比如 alias、代理、环境变量注入）时，必须操作 vite.config.ts（或 vite.config.js），这个文件在项目根目录，由 uni-app 初始化时自动创建。

注意：uni-app 的 Vite 配置有特殊要求——必须导出一个包裹了 defineConfig 的函数，并传入 defineUniAppConfig，否则 H5 端可能无法正确解析 pages.json 或条件编译。

正确写法示例：

import { defineConfig } from 'vite'
import { defineUniAppConfig } from '@dcloudio/vite-plugin-uni'

export default defineConfig({
  plugins: [defineUniAppConfig()],
  resolve: {
    alias: {
      '@': '/src'
    }
  }
})

直接写 export default defineConfig({ ... }) 不加 defineUniAppConfig() 插件，会导致 H5 端路由异常、uni.getSystemInfoSync() 返回空对象等隐性问题
小程序平台（微信/支付宝等）对 Vite 配置敏感度较低，但 H5 端必须走这套插件链

`process.env` 在 uni-app + Vite 中不能直接读取，要用 `import.meta.env`

Vue2 时代习惯的 process.env.NODE_ENV 在 Vite 下不可用，Vite 只识别 import.meta.env，且只有以 VUE_APP_ 或 UNI_APP 开头的环境变量才会被注入（uni-app 有定制规则）。

比如你在 .env.development 里写了 API_BASE_URL=https://dev.example.com，直接 import.meta.env.API_BASE_URL 是 undefined —— 必须改成 UNI_APP_API_BASE_URL 才行。

合法前缀只有：UNI_APP_、VUE_APP_、NODE_ENV、BASE_URL（后两者是 Vite 内置）
环境变量文件名必须是 .env、.env.development、.env.production，其他如 .env.local 不生效
修改环境变量后必须重启开发服务器，Vite 不会热更新这些值

插件兼容性是最大雷区：不是所有 Vite 插件都能用

uni-app 的构建流程在 Vite 上做了深度封装，尤其多端编译阶段（把同一份代码转成微信小程序、H5、App 等），很多通用 Vite 插件会破坏中间 AST 或资源处理逻辑。

典型翻车场景：加了 vite-plugin-mock 导致小程序编译卡死；用了 @vitejs/plugin-vue-jsx 后 uni.navigateTo 在 H5 报错；引入 vite-plugin-compression 后 App 端白屏。

优先使用 uni-app 官方维护的插件：@dcloudio/vite-plugin-uni（已内置）、@dcloudio/vite-plugin-uni-pages（页面自动注册）
想加第三方插件前，先查文档是否明确支持 “uni-app + Vite” 场景，别只看 “Vite 插件” 标签
调试时可临时注释插件，用 vite build --debug 观察日志输出点，定位是哪一步挂掉

真正麻烦的从来不是配 Vite，而是配完之后发现某个插件让微信小程序突然不认 pages.json 里的页面路径——这种问题没有报错提示，只能靠排除法一点点试。