移动端开发

前置准备

环境要求

工具	版本	用途
Node.js	≥ 18	运行时
pnpm	≥ 8	包管理
Android Studio	最新稳定版	原生构建
JDK	17+	Gradle 编译
ADB	随 Android SDK	设备调试

安装依赖

pnpm install

启动开发服务器

pnpm dev:m # 移动端 dev server（端口 3001）

浏览器访问 http://localhost:3001，使用浏览器开发者工具的移动端模拟器预览。

npm scripts

命令	说明
pnpm dev:m	启动移动端开发服务器（端口 3001）
pnpm build:m	类型检查 + 生产构建（输出到 dist/mobile/）
pnpm cap:sync	构建移动端 + Capacitor 同步到 Android 项目
pnpm cap:deploy	一键构建 + 同步 + 编译 APK + 安装到手机
pnpm lint	oxlint 代码检查
pnpm lint:fix	自动修复 lint 问题
pnpm format	oxfmt 代码格式化
pnpm type-check	TypeScript 类型检查

环境变量

环境变量定义在 .env、.env.develop、.env.production 中。

共用变量（.env）

VITE_BASE_URL=/ # 应用基础路径

VITE_API_URL_PREFIX=/api # API 请求前缀

VITE_APP_NAMESPACE=hmx-tdweb # Store 加密/缓存命名空间

VITE_APP_STORE_SECURE_KEY=... # Store 持久化加密密钥

VITE_ROUTER_NAMESPACE=TDWEB # PC 端路由命名空间

VITE_MOBILE_ROUTER_NAMESPACE=TDMOB # 移动端路由命名空间（动态菜单权限组）

VITE_APP_NAME="邢台铁特钢贸系统"

环境覆盖（.env.develop / .env.production）

VITE_API_URL=https://e.ttxcl.cn # 后端 API 地址

构建时环境变量

移动端构建通过 cross-env VITE_MOBILE=true 注入，Vite 据此选择：

入口文件 ：index.m.html（移动端）vs index.html（PC 端）
输出目录 ：dist/mobile/ vs dist/pcweb/
开发端口 ：3001（移动端）vs 3000（PC 端）

项目结构

src/
├── core/                          # 框架核心层
│   ├── shared/                    # PC/移动端共享
│   │   ├── api/                   #   API 请求封装（requestClient、权限、路由转换）
│   │   ├── components/            #   共享组件（Captcha、ThemeToggle、Mask）
│   │   ├── composables/           #   共享组合式函数（useRequest、usePermission）
│   │   ├── guards/                #   路由守卫（permission.ts，PC/移动端复用）
│   │   ├── plugins/               #   插件注册（Pinia + SecureLS）
│   │   ├── store/                 #   用户 Store（userStore.ts）
│   │   └── types/                 #   共享类型定义
│   └── m/                         # 移动端核心扩展（预留）
│
├── modules/
│   ├── m/                         # ⭐ 移动端业务模块
│   │   ├── main.ts                #   移动端入口
│   │   ├── main.vue               #   根组件（router-view + BottomNav）
│   │   ├── router/                #   路由配置
│   │   ├── pages/                 #   页面组件
│   │   │   ├── _core/             #     核心页面（登录、首页、工作台、我的）
│   │   │   └── workspace/         #     工作台功能页面
│   │   ├── components/            #   移动端组件
│   │   ├── composables/           #   移动端组合式函数
│   │   ├── stores/                #   移动端 Store
│   │   ├── layouts/               #   布局组件
│   │   ├── styles/                #   全局样式（Tailwind + 主题变量）
│   │   └── utils/                 #   工具函数（Capacitor、扫码、状态栏）
│   │
│   ├── pc/                        # PC 端业务模块（参考）
│   └── shared/                    # PC/移动端共享业务组件、Store、资源

路径别名

别名	实际路径
@/	src/
@core/	src/core/
@modules/	src/modules/
@shared/	src/core/shared/
@styles/	src/style/

新增页面

页面文件位置

移动端页面统一放在 src/modules/m/pages/ 下：

pages/
├── _core/                         # 核心页面（登录、首页、工作台、我的）
│   ├── LoginView.vue
│   ├── HomeView.vue
│   ├── WorkspaceView.vue
│   ├── ProfileView.vue
│   ├── PasswordView.vue
│   └── NotFoundView.vue
│
└── workspace/                     # 工作台功能页面（按业务分组）
    ├── MaterialView.vue
    ├── CustomerView.vue
    ├── WarehouseView.vue
    ├── ScanDemo.vue
    ├── InventoryCountView.vue
    └── PhotoInspectView.vue

Capacitor 原生集成

Android 项目结构

android/
├── app/
│   ├── src/main/
│   │   ├── java/.../             # Java/Kotlin 原生代码
│   │   ├── res/                  # 原生资源
│   │   └── AndroidManifest.xml
│   └── build.gradle
├── gradle/
└── build.gradle

常用 Capacitor 命令

bash

# 同步 Web 资源到 Android 项目
pnpm cap:sync

# 打开 Android Studio
pnpm cap:open android

# 编译并安装到设备
pnpm cap:deploy

原生插件使用

typescript

// 扫码功能
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanner';

const result = await BarcodeScanner.scan();

// 相机拍照
import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({
  quality: 90,
  resultType: CameraResultType.Base64
});

// 本地存储
import { Preferences } from '@capacitor/preferences';

await Preferences.set({ key: 'user', value: JSON.stringify(user) });

调试技巧

Chrome 远程调试

手机开启 USB 调试
连接电脑，访问 chrome://inspect/#devices
找到 WebView，点击 inspect

VConsole 调试

在开发环境启用 VConsole：

typescript

// main.ts
if (import.meta.env.DEV) {
  import('vconsole').then(({ default: VConsole }) => {
    new VConsole();
  });
}

发布构建

APK 构建流程

bash

# 1. 构建 Web 资源
pnpm build:m

# 2. 同步到 Android 项目
pnpm cap:sync

# 3. 打开 Android Studio 编译 APK
pnpm cap:open android

# 或一键完成（构建+同步+编译+安装）
pnpm cap:deploy

签名配置

在 Android Studio 中配置签名：

Build → Generate Signed Bundle/APK
选择 APK
创建或选择 keystore 文件
填写密钥信息
选择 release 构建类型

移动端开发 ​

前置准备 ​

npm scripts ​

环境变量 ​

项目结构 ​

新增页面 ​

Capacitor 原生集成 ​

Android 项目结构 ​

常用 Capacitor 命令 ​

原生插件使用 ​

调试技巧 ​

Chrome 远程调试 ​

VConsole 调试 ​

发布构建 ​

APK 构建流程 ​

签名配置 ​