从零搭建 Vue 移动端项目

移动端开发是前端工程师的核心技能之一，Vue 作为国内最主流的前端框架，结合成熟的移动端生态能快速搭建高性能的移动端项目。本文将从环境准备、项目创建、移动端适配、核心配置到功能开发，完整讲解 Vue 移动端项目的搭建流程，适合前端初学者和想系统化学习 Vue 移动端开发的同学。

一、前期准备：环境搭建

在创建 Vue 移动端项目前，需先配置好基础开发环境，确保后续流程顺畅。

1. 安装 Node.js 和 npm/yarn

Vue 项目依赖 Node.js 的包管理工具（npm/yarn/pnpm），建议安装 LTS 长期支持版：

下载地址：Node.js 官网（推荐 16.x/18.x 版本）
验证安装：安装完成后打开终端，执行以下命令，显示版本号即成功： bash

运行
复制代码
```
node -v  # 查看Node版本
npm -v   # 查看npm版本
```
可选：替换 npm 镜像源（解决下载慢问题） bash

运行
复制代码
```
npm config set registry https://registry.npmmirror.com
```
可选：安装 yarn（推荐，包安装速度更快） bash

运行
复制代码
```
npm install -g yarn
yarn -v  # 验证安装
```

2. 安装 Vue 脚手架（@vue/cli）

Vue 官方提供的脚手架工具能快速生成标准化项目结构：

bash

运行

复制代码

# 全局安装Vue CLI
npm install -g @vue/cli
# 验证安装
vue --version

注意：如果已安装旧版本，先执行 npm uninstall -g @vue/cli 卸载后再重装。

二、创建 Vue 移动端项目

1. 初始化项目

执行以下命令创建项目，本文以 Vue 3 + Vite 为例（Vite 比 Webpack 更快，更适合移动端开发）：

bash

运行

复制代码

# 创建项目（Vite版，推荐）
npm create vue@latest mobile-vue-demo

执行后会出现交互式配置选项，推荐配置如下：

plaintext

复制代码

✔ Project name: ... mobile-vue-demo （项目名，自定义）
✔ Add TypeScript? ... No/Yes （可选，新手选No）
✔ Add JSX/TSX support? ... No
✔ Add Vue Router for Single Page Application development? ... Yes （必选，移动端路由必备）
✔ Add Pinia for state management? ... Yes （可选，状态管理）
✔ Add Vitest for Unit Testing? ... No
✔ Add an End-to-End Testing Solution? ... No
✔ Add ESLint for code quality? ... Yes （代码规范，推荐）
✔ Add Prettier for code formatting? ... Yes

配置完成后，进入项目目录并安装依赖：

bash

运行

复制代码

cd mobile-vue-demo
npm install  # 或 yarn install

2. 启动项目验证

bash

运行

复制代码

npm run dev  # 启动开发服务器

终端会显示本地访问地址（如http://127.0.0.1:5173/），打开浏览器访问，能看到 Vue 默认页面即项目创建成功。

三、移动端核心配置：适配方案

移动端最关键的问题是多设备适配，本文推荐两种主流方案，按需选择。

方案 1：rem 适配（基于 amfe-flexible + postcss-pxtorem）

rem 是相对根节点的单位，通过动态设置 html 的 font-size 实现适配，兼容所有移动端浏览器。

步骤 1：安装依赖

bash

运行

复制代码

npm install amfe-flexible postcss-pxtorem --save

amfe-flexible：阿里开源的移动端适配库，动态设置 html 的 font-size
postcss-pxtorem：自动将 px 转换为 rem 的 PostCSS 插件

步骤 2：配置 amfe-flexible

在项目入口文件src/main.js中引入：

复制代码

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
// 引入移动端适配
import 'amfe-flexible'

createApp(App).use(router).mount('#app')

步骤 3：配置 postcss-pxtorem

在项目根目录创建postcss.config.js文件，添加以下配置：

复制代码

module.exports = {
  plugins: {
    'postcss-pxtorem': {
      rootValue: 37.5,  // 设计稿宽度的1/10（假设设计稿是375px）
      propList: ['*'],  // 所有属性都转换为rem
      selectorBlackList: ['van-'], // 排除vant组件（vant默认基于375px设计）
      exclude: /node_modules/i // 排除node_modules目录
    }
  }
}

说明：如果设计稿是 750px，rootValue 设为 75，但 vant 组件需单独处理（建议设计稿统一用 375px）。

方案 2：vw/vh 适配（纯 CSS 方案）

vw/vh 是视口单位，1vw = 视口宽度的 1%，无需 JS 介入，更简洁：

无需安装依赖，直接在 CSS 中使用 vw 单位

示例（设计稿 375px，元素宽度 100px）： css

复制代码

.box {
  width: 26.667vw; /* 100/375*100 = 26.667 */
  height: 13.333vw; /* 50/375*100 = 13.333 */
}

优点：无兼容性问题（移动端浏览器均支持），无需配置；缺点：需手动计算或用插件转换 px 到 vw。

四、集成移动端 UI 组件库

移动端开发无需重复造轮子，推荐集成成熟的 UI 库，本文以 Vant 为例（Vue 3 适配的轻量移动端组件库）。

1. 安装 Vant

bash

运行

复制代码

# Vue 3 + Vite 安装Vant 4
npm i vant

2. 自动按需引入组件（推荐）

Vant 支持按需引入，减小打包体积：

bash

运行

复制代码

# 安装按需引入插件
npm i unplugin-vue-components unplugin-auto-import -D

修改vite.config.js配置：

复制代码

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
// 引入Vant按需引入插件
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from 'unplugin-vue-components/resolvers';

export default defineConfig({
  plugins: [
    vue(),
    // 配置Vant按需引入
    Components({
      resolvers: [VantResolver()],
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  // 移动端适配：设置开发服务器端口，解决跨域（可选）
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'https://api.example.com', // 后端接口地址
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

3. 使用 Vant 组件

在 Vue 组件中直接使用，无需手动引入：

vue

复制代码

<template>
  <van-button type="primary" @click="handleClick">按钮</van-button>
  <van-cell-group>
    <van-cell title="单元格" value="内容" />
  </van-cell-group>
</template>

<script setup>
const handleClick = () => {
  console.log('按钮点击')
}
</script>

五、移动端核心功能开发示例

1. 路由配置（适配移动端页面跳转）

修改src/router/index.js，配置移动端页面路由：

复制代码

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: () => import('../views/HomeView.vue') // 首页
    },
    {
      path: '/detail',
      name: 'detail',
      component: () => import('../views/DetailView.vue') // 详情页
    }
  ]
})

// 移动端路由守卫（可选）
router.beforeEach((to, from, next) => {
  // 隐藏移动端键盘、处理页面切换动画等
  next()
})

export default router

2. 移动端交互处理

（1）点击事件优化

移动端点击有 300ms 延迟，可通过@touchstart替代@click，或使用 Vant 的FastClick：

vue

复制代码

<template>
  <div @touchstart="handleTouch">快速点击</div>
</template>

（2）下拉刷新 / 上拉加载

使用 Vant 的PullRefresh和List组件：

vue

复制代码

<template>
  <van-pull-refresh v-model="refreshing" @refresh="onRefresh">
    <van-list
      v-model:loading="loading"
      :finished="finished"
      finished-text="没有更多了"
      @load="onLoad"
    >
      <van-cell v-for="item in list" :key="item" :title="item" />
    </van-list>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue'

const refreshing = ref(false)
const loading = ref(false)
const finished = ref(false)
const list = ref([])

const onRefresh = () => {
  // 模拟下拉刷新
  setTimeout(() => {
    list.value = Array.from({ length: 10 }, (_, i) => `刷新后数据 ${i}`)
    refreshing.value = false
  }, 1000)
}

const onLoad = () => {
  // 模拟上拉加载
  setTimeout(() => {
    for (let i = 0; i < 10; i++) {
      list.value.push(`加载后数据 ${list.value.length}`)
    }
    loading.value = false
    // 数据加载完成
    if (list.value.length >= 30) {
      finished.value = true
    }
  }, 1000)
}
</script>

六、项目打包与发布

1. 打包配置

修改vite.config.js中的打包配置，优化移动端打包体积：

复制代码

export default defineConfig({
  // ...其他配置
  build: {
    outDir: 'dist', // 打包输出目录
    assetsDir: 'static', // 静态资源目录
    minify: 'terser', // 压缩代码
    terserOptions: {
      compress: {
        drop_console: true, // 移除console.log
        drop_debugger: true // 移除debugger
      }
    },
    rollupOptions: {
      output: {
        // 分包，减小主包体积
        chunkFileNames: 'static/js/[name]-[hash].js',
        entryFileNames: 'static/js/[name]-[hash].js',
        assetFileNames: 'static/[ext]/[name]-[hash].[ext]'
      }
    }
  }
})

2. 执行打包

bash

运行

复制代码

npm run build

打包完成后，dist目录即为可部署的静态文件。

3. 移动端调试与发布

本地调试：使用手机连接同一局域网，访问电脑 IP + 端口（如http://192.168.1.100:5173）
真机调试：使用 Chrome 的chrome://inspect或 Safari 调试 iOS 设备
发布：将dist目录上传到 Nginx、阿里云 OSS、Netlify 等静态服务器

七、常见问题与解决方案

适配问题：不同设备显示不一致 → 确保 rem/vw 配置正确，设计稿统一用 375px 基准
点击穿透 ：弹窗关闭后触发底层点击 → 使用@touchstart.stop阻止冒泡
打包体积过大：按需引入组件、开启 gzip 压缩、拆分第三方库
移动端键盘遮挡输入框 ：监听resize事件，动态调整页面高度

八、总结

本文完整讲解了 Vue 移动端项目的搭建流程：从环境准备→项目创建→适配配置→UI 库集成→功能开发→打包发布，核心是解决移动端适配和交互问题。实际开发中可根据项目需求选择适配方案（rem/vw）、扩展更多功能（如支付、分享、定位），并结合 ESLint、Prettier 保证代码规范。

掌握这套流程后，你可以快速搭建各类 Vue 移动端项目（电商、资讯、工具类 App），后续可深入学习 Vue 3 的组合式 API、Vite 优化、移动端性能调优等内容，提升项目体验。