vue/APP_GUIDE.md

网盘管理系统 - APP 打包指南

📱 项目说明

这是一个基于 Vue 3 + Capacitor 的跨平台移动应用，支持 Android 和 iOS。

🛠️ 技术栈

• 前端框架: Vue 3 (Composition API)
• 构建工具: Vite
• 跨平台方案: Capacitor
• UI 样式: 原生 CSS（移动端适配）

📦 安装依赖

npm install

🚀 开发模式

Web 开发

npm run dev

Android 开发

# 1. 构建 Web 资源
npm run build

# 2. 同步到 Android
npx cap sync android

# 3. 在 Android Studio 中打开
npx cap open android

iOS 开发（需要 macOS）

# 1. 添加 iOS 平台
npx cap add ios

# 2. 构建并同步
npm run build
npx cap sync ios

# 3. 在 Xcode 中打开
npx cap open ios

🏗️ 打包发布

Android APK 打包

方法一：使用 Android Studio（推荐）

1. 运行 npx cap open android 打开 Android Studio
2. 等待 Gradle 同步完成
3. 点击菜单 Build → Build Bundle(s) / APK(s) → Build APK(s)
4. APK 文件会生成在 android/app/build/outputs/apk/debug/ 目录

方法二：命令行打包

cd android
./gradlew assembleDebug

APK 位置：android/app/build/outputs/apk/debug/app-debug.apk

发布版本（签名 APK）

1. 创建密钥库文件：

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

2. 在 android/app/build.gradle 中配置签名：

android {
    ...
    signingConfigs {
        release {
            storeFile file("../my-release-key.jks")
            storePassword "your-store-password"
            keyAlias "my-alias"
            keyPassword "your-key-password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

3. 打包：

./gradlew assembleRelease

📂 项目结构

wangpan/vue/
├── src/                    # 源代码
│   ├── api/               # API 接口
│   ├── components/        # Vue 组件
│   ├── utils/             # 工具函数
│   ├── App.vue           # 主组件
│   └── main.js           # 入口文件
├── android/               # Android 原生项目
├── ios/                   # iOS 原生项目（macOS）
├── dist/                  # 构建输出
├── public/                # 静态资源
├── capacitor.config.json  # Capacitor 配置
└── package.json

🔧 配置说明

Capacitor 配置 (capacitor.config.json)

{
  "appId": "com.wangpan.app",      // APP ID
  "appName": "网盘管理系统",         // APP 名称
  "webDir": "dist",                 // Web 资源目录
  "plugins": {
    "SplashScreen": {              // 启动屏配置
      "launchShowDuration": 2000,
      "backgroundColor": "#f8f9fc",
      "showSpinner": false
    },
    "StatusBar": {                 // 状态栏配置
      "style": "light",
      "backgroundColor": "#6366f1"
    }
  }
}

🎨 自定义图标和启动屏

更换 APP 图标

1. 准备图标文件（PNG 格式）：

   • 1024x1024 (Google Play 要求)
   • 512x512
   • 192x192
   • 144x144
   • 96x96
   • 72x72
   • 48x48

2. 替换 android/app/src/main/res/mipmap-*/ic_launcher.png

3. 或使用在线工具生成：https://icon.kitchen/

更换启动屏

1. 准备启动屏图片（PNG 格式）
2. 替换 android/app/src/main/res/drawable/splash.png
3. 或使用 Cordova 插件自动生成

🐛 常见问题

1. Android Studio 无法识别项目

• 确保已安装 JDK 11+
• 确保已安装 Android SDK
• 运行 npx cap sync android 重新同步

2. 白屏问题

• 检查 dist/ 目录是否有正确的构建文件
• 检查 capacitor.config.json 中的 webDir 配置
• 查看 Chrome DevTools: chrome://inspect/#devices

3. API 请求失败

• 确保后端服务已启动
• 检查 CORS 配置
• Android 需要配置网络安全策略（允许 HTTP）

4. 热重载不工作

• Capacitor 不支持热重载
• 修改代码后需要重新构建：npm run build && npx cap sync

📱 真机测试

Android 真机调试

1. 开启手机的开发者选项和 USB 调试
2. 连接手机到电脑
3. 在 Android Studio 中点击 Run 按钮
4. 或使用命令：

npx cap run android

Chrome 远程调试

1. 手机连接电脑
2. 浏览器访问 chrome://inspect/#devices
3. 选择你的设备进行调试

🔐 权限配置

如果需要访问相机、相册等权限，需要在 android/app/src/main/AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

📊 性能优化建议

1. 图片优化：使用 WebP 格式，压缩图片
2. 代码分割：使用动态导入 import()
3. 懒加载：路由和组件按需加载
4. 缓存策略：合理使用 localStorage 和 IndexedDB
5. 减少重绘：避免频繁操作 DOM

📝 更新日志

v1.0.0 (2026-06-08)

• ✅ 完成移动端适配
• ✅ 集成 Capacitor
• ✅ 支持 Android 打包
• ✅ 优化触摸交互
• ✅ 修复验证码拉伸问题

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License