📚 项目结构与基础配置

1. UniApp项目结构详解

1.1 标准项目结构

my-uniapp-project/
├── pages/                  # 页面文件目录
│   ├── index/             # 首页
│   │   ├── index.vue
│   │   └── index.scss
│   ├── logs/              # 日志页
│   │   └── logs.vue
│   └── tabBar/            # 底部导航页面
│       ├── home/
│       ├── category/
│       ├── cart/
│       └── user/
├── components/             # 组件目录
│   ├── common/            # 公共组件
│   │   ├── header.vue
│   │   ├── footer.vue
│   │   └── loading.vue
│   └── business/          # 业务组件
├── static/                # 静态资源目录
│   ├── images/            # 图片资源
│   ├── icons/             # 图标资源
│   ├── fonts/             # 字体文件
│   └── audio/             # 音频文件
├── common/                # 公共文件目录
│   ├── api/               # API接口
│   ├── utils/             # 工具函数
│   ├── config/            # 配置文件
│   └── constants/         # 常量定义
├── store/                 # 状态管理
│   ├── index.js
│   ├── modules/
│   └── getters.js
├── mixins/                # 混入
├── filters/               # 过滤器
├── App.vue                # 应用配置文件
├── main.js                # 入口文件
├── manifest.json          # 应用配置清单
├── pages.json             # 页面路由配置
├── uni.scss              # 全局样式变量
└── package.json           # 项目依赖配置

1.2 核心文件说明

App.vue - 应用根组件

<template>
    <!-- 应用模板，通常为空 -->
</template>

<script>
export default {
    // 应用生命周期
    onLaunch: function() {
        console.log('App Launch');
        // 应用启动时的逻辑
    },
    onShow: function() {
        console.log('App Show');
        // 应用显示时的逻辑
    },
    onHide: function() {
        console.log('App Hide');
        // 应用隐藏时的逻辑
    }
}
</script>

<style>
/* 全局样式 */
.container {
    padding: 20rpx;
}
</style>

main.js - 应用入口

import Vue from 'vue'
import App from './App'

// 引入全局组件
import uView from 'uview-ui'
Vue.use(uView)

// 引入全局混入
import mixins from './mixins'
Vue.mixin(mixins)

// 引入全局过滤器
import * as filters from './filters'
Object.keys(filters).forEach(key => {
    Vue.filter(key, filters[key])
})

// 配置
Vue.config.productionTip = false

// 挂载应用
App.mpType = 'app'

const app = new Vue({
    ...App
})
app.$mount()

2. 配置文件详解

2.1 pages.json - 页面配置

{
    "pages": [
        {
            "path": "pages/index/index",
            "style": {
                "navigationBarTitleText": "首页",
                "navigationBarBackgroundColor": "#007AFF",
                "navigationBarTextStyle": "white",
                "backgroundColor": "#f8f8f8",
                "enablePullDownRefresh": true,
                "onReachBottomDistance": 50
            }
        },
        {
            "path": "pages/logs/logs",
            "style": {
                "navigationBarTitleText": "日志"
            }
        }
    ],
    "globalStyle": {
        "navigationBarTextStyle": "black",
        "navigationBarTitleText": "UniApp",
        "navigationBarBackgroundColor": "#F8F8F8",
        "backgroundColor": "#F8F8F8",
        "app-plus": {
            "background": "#efeff4"
        }
    },
    "tabBar": {
        "color": "#7A7E83",
        "selectedColor": "#3cc51f",
        "borderStyle": "black",
        "backgroundColor": "#ffffff",
        "list": [
            {
                "pagePath": "pages/index/index",
                "iconPath": "static/tab-home.png",
                "selectedIconPath": "static/tab-home-current.png",
                "text": "首页"
            },
            {
                "pagePath": "pages/logs/logs",
                "iconPath": "static/tab-logs.png",
                "selectedIconPath": "static/tab-logs-current.png",
                "text": "日志"
            }
        ]
    },
    "condition": {
        "current": 0,
        "list": [
            {
                "name": "首页",
                "path": "pages/index/index",
                "query": ""
            }
        ]
    }
}

pages.json配置项说明

pages数组 - path: 页面路径 - style: 页面样式配置 - navigationBarTitleText: 导航栏标题 - navigationBarBackgroundColor: 导航栏背景色 - navigationBarTextStyle: 导航栏文字颜色 - backgroundColor: 页面背景色 - enablePullDownRefresh: 是否开启下拉刷新 - onReachBottomDistance: 上拉触底距离

globalStyle全局样式 - 应用于所有页面的默认样式 - 可被页面级style覆盖

tabBar底部导航 - color: 未选中时的文字颜色 - selectedColor: 选中时的文字颜色 - backgroundColor: 背景色 - list: 导航项配置

2.2 manifest.json - 应用配置

{
    "name": "my-uniapp",
    "appid": "__UNI__XXXXXX",
    "description": "UniApp应用描述",
    "versionName": "1.0.0",
    "versionCode": "100",
    "transformPx": false,
    "app-plus": {
        "usingComponents": true,
        "nvueStyleCompiler": "uni-app",
        "compilerVersion": 3,
        "splashscreen": {
            "alwaysShowBeforeRender": true,
            "waiting": true,
            "autoclose": true,
            "delay": 0
        },
        "modules": {},
        "distribute": {
            "android": {
                "permissions": [
                    "<uses-permission android:name=\"android.permission.CHANGE_NETWORK_STATE\" />",
                    "<uses-permission android:name=\"android.permission.MOUNT_UNMOUNT_FILESYSTEMS\" />",
                    "<uses-permission android:name=\"android.permission.VIBRATE\" />",
                    "<uses-permission android:name=\"android.permission.READ_LOGS\" />",
                    "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\" />",
                    "<uses-feature android:name=\"android.hardware.camera.autofocus\" />",
                    "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />",
                    "<uses-permission android:name=\"android.permission.CAMERA\" />",
                    "<uses-permission android:name=\"android.permission.GET_ACCOUNTS\" />",
                    "<uses-permission android:name=\"android.permission.READ_PHONE_STATE\" />",
                    "<uses-permission android:name=\"android.permission.CHANGE_WIFI_STATE\" />",
                    "<uses-permission android:name=\"android.permission.WAKE_LOCK\" />",
                    "<uses-permission android:name=\"android.permission.FLASHLIGHT\" />",
                    "<uses-permission android:name=\"android.permission.WRITE_SETTINGS\" />"
                ]
            },
            "ios": {},
            "sdkConfigs": {}
        }
    },
    "quickapp": {},
    "mp-weixin": {
        "appid": "wxXXXXXXXXXXXXXXXX",
        "setting": {
            "urlCheck": false
        },
        "usingComponents": true
    },
    "mp-alipay": {
        "usingComponents": true
    },
    "mp-baidu": {
        "usingComponents": true
    },
    "mp-toutiao": {
        "usingComponents": true
    },
    "uniStatistics": {
        "enable": false
    },
    "vueVersion": "3"
}

manifest.json配置项说明

基础配置 - name: 应用名称 - appid: 应用ID - description: 应用描述 - versionName: 版本名称 - versionCode: 版本号

平台配置 - app-plus: App平台配置 - mp-weixin: 微信小程序配置 - mp-alipay: 支付宝小程序配置 - h5: H5平台配置

2.3 uni.scss - 全局样式变量

/* 颜色变量 */
$uni-color-primary: #007aff;
$uni-color-success: #4cd964;
$uni-color-warning: #f0ad4e;
$uni-color-error: #dd524d;

/* 文字基本颜色 */
$uni-text-color: #333;
$uni-text-color-inverse: #fff;
$uni-text-color-grey: #999;
$uni-text-color-placeholder: #808080;
$uni-text-color-disable: #c0c0c0;

/* 背景颜色 */
$uni-bg-color: #ffffff;
$uni-bg-color-grey: #f8f8f8;
$uni-bg-color-hover: #f1f1f1;
$uni-bg-color-mask: rgba(0, 0, 0, 0.4);

/* 边框颜色 */
$uni-border-color: #e5e5e5;

/* 尺寸变量 */
$uni-spacing-row-sm: 5px;
$uni-spacing-row-base: 10px;
$uni-spacing-row-lg: 15px;
$uni-spacing-col-sm: 5px;
$uni-spacing-col-base: 10px;
$uni-spacing-col-lg: 15px;

/* 圆角 */
$uni-border-radius-sm: 2px;
$uni-border-radius-base: 3px;
$uni-border-radius-lg: 6px;
$uni-border-radius-circle: 50%;

/* 字体大小 */
$uni-font-size-sm: 24rpx;
$uni-font-size-base: 28rpx;
$uni-font-size-lg: 32rpx;

/* 自定义变量 */
$custom-color-primary: #3c9cff;
$custom-color-info: #909399;
$custom-color-default: #909399;
$custom-color-warning: #f9ae3d;
$custom-color-error: #f56c6c;
$custom-color-success: #5ac725;
$custom-color-mainColor: #303133;
$custom-color-contentColor: #606266;
$custom-color-tipsColor: #909399;
$custom-color-lightColor: #c0c4cc;

3. 环境配置

3.1 开发环境配置

创建配置文件

// common/config/env.js
const config = {
    development: {
        baseUrl: 'http://localhost:3000',
        apiUrl: 'http://localhost:3000/api',
        imageUrl: 'http://localhost:3000/images'
    },
    production: {
        baseUrl: 'https://api.example.com',
        apiUrl: 'https://api.example.com/api',
        imageUrl: 'https://cdn.example.com/images'
    }
}

// 根据编译环境选择配置
const env = process.env.NODE_ENV === 'development' ? 'development' : 'production'

export default config[env]

使用配置

// 在页面或组件中使用
import config from '@/common/config/env.js'

export default {
    data() {
        return {
            apiUrl: config.apiUrl
        }
    },
    methods: {
        fetchData() {
            uni.request({
                url: `${this.apiUrl}/users`,
                success: (res) => {
                    console.log(res.data)
                }
            })
        }
    }
}

3.2 条件编译配置

// #ifdef APP-PLUS
// App平台特有代码
const platform = 'app'
// #endif

// #ifdef MP-WEIXIN
// 微信小程序特有代码
const platform = 'weixin'
// #endif

// #ifdef H5
// H5平台特有代码
const platform = 'h5'
// #endif

// #ifndef H5
// 除H5平台外的代码
const hasTabBar = true
// #endif

3.3 TypeScript配置

安装TypeScript支持

npm install typescript @types/uni-app -D

创建tsconfig.json

{
    "compilerOptions": {
        "target": "es5",
        "lib": ["dom", "dom.iterable", "es6"],
        "allowJs": true,
        "skipLibCheck": true,
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "strict": true,
        "forceConsistentCasingInFileNames": true,
        "module": "esnext",
        "moduleResolution": "node",
        "resolveJsonModule": true,
        "isolatedModules": true,
        "noEmit": true,
        "jsx": "preserve",
        "baseUrl": ".",
        "paths": {
            "@/*": ["./src/*"]
        },
        "types": ["@types/uni-app"]
    },
    "include": [
        "src/**/*",
        "types/**/*"
    ],
    "exclude": [
        "node_modules"
    ]
}

4. 项目配置最佳实践

4.1 目录结构规范

src/
├── api/                   # API接口层
│   ├── modules/          # 按模块分类
│   │   ├── user.js
│   │   ├── product.js
│   │   └── order.js
│   ├── request.js        # 请求封装
│   └── index.js          # API统一导出
├── components/           # 组件
│   ├── common/          # 通用组件
│   └── business/        # 业务组件
├── pages/               # 页面
├── static/              # 静态资源
├── store/               # 状态管理
├── utils/               # 工具函数
├── mixins/              # 混入
├── filters/             # 过滤器
└── styles/              # 样式文件
    ├── common.scss      # 公共样式
    ├── variables.scss   # 变量
    └── mixins.scss      # 样式混入

4.2 配置文件管理

统一配置管理

// common/config/index.js
import env from './env.js'
import api from './api.js'
import constants from './constants.js'

export default {
    env,
    api,
    constants
}

API配置

// common/config/api.js
export default {
    // 用户相关
    user: {
        login: '/auth/login',
        logout: '/auth/logout',
        profile: '/user/profile'
    },
    // 产品相关
    product: {
        list: '/products',
        detail: '/products/{id}',
        search: '/products/search'
    }
}

4.3 样式配置规范

主题配置

// styles/theme.scss
:root {
    --primary-color: #007aff;
    --success-color: #4cd964;
    --warning-color: #f0ad4e;
    --error-color: #dd524d;
    
    --text-color: #333;
    --text-color-light: #666;
    --text-color-lighter: #999;
    
    --border-color: #e5e5e5;
    --bg-color: #f8f8f8;
}

// 暗黑模式
@media (prefers-color-scheme: dark) {
    :root {
        --text-color: #fff;
        --bg-color: #1a1a1a;
        --border-color: #333;
    }
}

响应式断点

// styles/breakpoints.scss
$breakpoints: (
    xs: 0,
    sm: 576px,
    md: 768px,
    lg: 992px,
    xl: 1200px
);

@mixin respond-to($breakpoint) {
    @if map-has-key($breakpoints, $breakpoint) {
        @media (min-width: map-get($breakpoints, $breakpoint)) {
            @content;
        }
    }
}

5. 性能配置优化

5.1 编译优化

// vue.config.js
module.exports = {
    transpileDependencies: ['uview-ui'],
    configureWebpack: {
        optimization: {
            splitChunks: {
                chunks: 'all',
                cacheGroups: {
                    vendor: {
                        name: 'vendor',
                        test: /[\\/]node_modules[\\/]/,
                        chunks: 'all',
                        priority: 10
                    },
                    common: {
                        name: 'common',
                        minChunks: 2,
                        chunks: 'all',
                        priority: 5
                    }
                }
            }
        }
    }
}

5.2 资源优化配置

// manifest.json中的优化配置
{
    "h5": {
        "optimization": {
            "treeShaking": {
                "enable": true
            }
        },
        "router": {
            "mode": "hash",
            "base": "./"
        }
    },
    "mp-weixin": {
        "optimization": {
            "subPackages": true
        }
    }
}

6. 总结

本章详细介绍了UniApp项目的结构组织和基础配置：

1. 项目结构：了解了标准的目录结构和文件组织方式
2. 核心配置：掌握了pages.json、manifest.json等关键配置文件
3. 样式配置：学习了uni.scss全局样式变量的使用
4. 环境配置：了解了多环境配置和条件编译
5. 最佳实践：掌握了项目配置的规范和优化方法

良好的项目结构和配置是开发高质量UniApp应用的基础，下一章我们将学习页面与组件的开发。