vue3 + vite 移动端 h5 项目，通过 HBuilderX 打包成安卓 APP

背景

用 vue3 + vite 开发一个移动端 h5 项目。开发完成后，又有新需求，需要将这个项目打包成安卓 APP。

1、配置 vite.config.ts（重点是其中的 base 属性配置）

import { resolve } from 'node:path'
import type { ConfigEnv, UserConfig } from 'vite'
import { loadEnv } from 'vite'
import { format } from 'date-fns'
import { wrapperEnv } from './build/utils'
import { createVitePlugins } from './build/vite/plugin'
import { OUTPUT_DIR } from './build/constant'
import { createProxy } from './build/vite/proxy'
import pkg from './package.json'

const { dependencies, devDependencies, name, version } = pkg

function pathResolve(dir: string) {
  return resolve(process.cwd(), '.', dir)
}

const __APP_INFO__ = {
  // APP 后台管理信息
  pkg: { dependencies, devDependencies, name, version },
  // 最后编译时间
  lastBuildTime: format(new Date(), 'yyyy-MM-dd HH:mm:ss')
}

/** @type {import('vite').UserConfig} */
export default ({ command, mode }: ConfigEnv): UserConfig => {
  const root = process.cwd()
  const env = loadEnv(mode, root)
  const viteEnv = wrapperEnv(env)

  const { VITE_PUBLIC_PATH, VITE_DROP_CONSOLE, VITE_PORT, VITE_PROXY, VITE_GLOB_PROD_MOCK } = viteEnv

  const prodMock = VITE_GLOB_PROD_MOCK

  const isBuild = command === 'build'
  // command === 'build'
  return {
    base: './', //重点在这个地方，打包的时候需要设置成相对路径，不然打包后安卓APP无法访问资源
    // base: '/h5',  //这个是h5版本的打包配置，因为项目访问地址是域名后面+/h5，所以需要设置成这个

    root,

    // 别名
    resolve: {
      alias: [
        // @/xxxx => src/xxxx
        {
          find: /\@\//,
          replacement: `${pathResolve('src')}/`
        },
        // #/xxxx => types/xxxx
        {
          find: /\#\//,
          replacement: `${pathResolve('types')}/`
        }
      ],
      dedupe: ['vue']
    },

    // 定义全局常量替换方式
    define: {
      // 在生产中 启用/禁用 intlify-devtools 和 vue-devtools 支持，默认值 false
      __INTLIFY_PROD_DEVTOOLS__: false,
      __APP_INFO__: JSON.stringify(__APP_INFO__),
      'process.env': {
        // 将 Vite 的环境变量映射到 process.env
        NODE_ENV: env.NODE_ENV,
        // 可按需添加其他需要的变量（如第三方组件依赖的变量）
        VITE_GLOB_API_URL_PREFIX: env.VITE_GLOB_API_URL_PREFIX,
        VITE_APP_BASE_URL: env.VITE_APP_BASE_URL
        // ...其他变量
      }
    },

    esbuild: {
      // 使用 esbuild 压缩 剔除 console.log
      drop: VITE_DROP_CONSOLE ? ['debugger', 'console'] : []
      // minify: true, // minify: true, 等于 minify: 'esbuild',
    },

    build: {
      // 设置最终构建的浏览器兼容目标
      target: 'es2015',
      minify: 'esbuild',
      // 构建后是否生成 source map 文件(用于线上报错代码报错映射对应代码)
      sourcemap: false,
      cssTarget: 'chrome80',
      // 指定输出路径（相对于 项目根目录)
      outDir: OUTPUT_DIR,
      // 只有 minify 为 terser 的时候, 本配置项才能起作用
      // terserOptions: {
      //   compress: {
      //     // 防止 Infinity 被压缩成 1/0，这可能会导致 Chrome 上的性能问题
      //     keep_infinity: true,
      //     // 打包是否自动删除 console
      //     drop_console: VITE_DROP_CONSOLE,
      //   },
      // },
      // 启用/禁用 gzip 压缩大小报告
      // 压缩大型输出文件可能会很慢，因此禁用该功能可能会提高大型项目的构建性能
      reportCompressedSize: true,
      // chunk 大小警告的限制（以 kbs 为单位）
      chunkSizeWarningLimit: 2000,
      commonjsOptions: {
        include: /node_modules|lib/ //这里记得把lib目录加进来，否则生产打包会报错！！
      },
      // 自定义底层的 Rollup 打包配置
      rollupOptions: {
        // 静态资源分类打包
        output: {
          chunkFileNames: 'js/[name]-[hash].js', // 引入文件名的名称
          entryFileNames: 'js/[name]-[hash].js', // 包的入口文件名称
          assetFileNames: '[ext]/[name]-[hash].[ext]', // 资源文件像 字体，图片等
          // 将 node_modules 三方依赖包最小化拆分
          manualChunks(id) {
            if (id.includes('node_modules') && !id.includes('@antv')) {
              const paths = id.toString().split('node_modules/')
              if (paths[2]) {
                return paths[2].split('/')[0].toString()
              }

              return paths[1].split('/')[0].toString()
            }
          }
        }
      }
    },

    css: {
      preprocessorOptions: {
        less: {
          modifyVars: {},
          javascriptEnabled: true,
          // 注入全局 less 变量
          additionalData: `@import "src/styles/var.less";`
        }
      }
    },

    server: {
      host: true,
      // 服务启动时是否自动打开浏览器
      open: true,
      // 服务端口号
      port: Number(VITE_PORT),
      proxy: createProxy(VITE_PROXY),
      // 预热文件以降低启动期间的初始页面加载时长
      warmup: {
        // 预热的客户端文件：首页、views、 components
        clientFiles: ['./index.html', './src/{views,components}/*']
      }
      // proxy: {
      //     '/api': {
      //         target: '',
      //         changeOrigin: true,
      //         rewrite: (path) => path.replace(/^\/api/, '/api/v1')
      //     }
      // }
    },

    optimizeDeps: {
      /**
       * 依赖预构建，vite 启动时会将下面 include 里的模块，编译成 esm 格式并缓存到 node_modules/.vite 文件夹，
       * 页面加载到对应模块时如果浏览器有缓存就读取浏览器缓存，如果没有会读取本地缓存并按需加载
       * 尤其当您禁用浏览器缓存时（这种情况只应该发生在调试阶段）必须将对应模块加入到 include 里，
       * 否则会遇到开发环境切换页面卡顿的问题（vite 会认为它是一个新的依赖包会重新加载并强制刷新页面），
       * 因为它既无法使用浏览器缓存，又没有在本地 node_modules/.vite 里缓存
       * 温馨提示：如果你使用的第三方库是全局引入，也就是引入到 src/main.ts 文件里，
       * 就不需要再添加到 include 里了，因为 vite 会自动将它们缓存到 node_modules/.vite
       */
      include: ['pinia', 'lodash-es', 'axios', '@/../lib/vform/render.umd.js'],
      // 打包时强制排除的依赖项
      exclude: [
        // https://www.mulingyuer.com/archives/928/
        'vant',
        '@vant/use'
      ]
    },

    // 加载插件
    plugins: createVitePlugins(viteEnv, isBuild, prodMock)
  }
}

2、确保路由模式为 hash

import { App } from 'vue'
import { createRouter, createWebHashHistory, RouteRecordRaw, createWebHistory } from 'vue-router'
import { LoginRoute, RootRoute, ErrorPageRoute, NoRightRoute } from '@/router/base'
import { createRouterGuards } from './router-guards'
import { useRouteStoreWidthOut } from '@/store/modules/route'

// 菜单
import routeModuleList from './modules'

// 普通路由
export const constantRouter: RouteRecordRaw[] = [NoRightRoute, LoginRoute, RootRoute, ErrorPageRoute]

const routeStore = useRouteStoreWidthOut()

routeStore.setMenus(routeModuleList)
routeStore.setRouters(constantRouter.concat(routeModuleList))

const router = createRouter({
  history: createWebHashHistory(), // 确保打包时候的路由模式为 hash
  // history: createWebHistory('/h5'),
  routes: constantRouter.concat(...routeModuleList),
  strict: true,
  scrollBehavior: () => ({ left: 0, top: 0 })
})

export function setupRouter(app: App) {
  app.use(router)
  // 创建路由守卫
  createRouterGuards(router)
}

export default router

3、设置.env.production 文件中的根目录

# 网站根目录
VITE_PUBLIC_PATH=./

4、在 HBuilderX 创建 5+app 项目，打包 APP

• 在 HBuilderX 创建 5+app 项目，保留项目中的 unpackage 文件夹和 manifest.json 文件。将 vue 项目 build 后 dist 文件夹中的文件复制到新建项目的根目录。

• 单击 manifest.json 文件，修改配置，第一次搞这个的话，appID 应该是没有的，你可以点击一下“重新获取”按钮。另外【模块配置】中的 Contact 尽量不要勾选。【权限配置】中关于“CONTACTS”的权限删除。

• 然后在 HBuilderX 中点击【发行】->【原生 App-云打包】，证书选择【使用云端证书】。这个是免费的，但是每天使用次数是有限的。底下开屏广告的可以不要。配置完成后，点击右下角的【打包】按钮，等着就行。

提示

如果打包成 APP 后，发现页面空白，可以跑一下 vue 项目 build 出的 dist 文件，看看报错信息，是不是哪里配置的不对。