uni-app Vue 项目的规范目录结构全解

前些天发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到网站。

文章目录

• [uni-app Vue 项目的规范目录结构全解](#uni-app Vue 项目的规范目录结构全解)
• • 引言
  • [📂 目录结构解析](#📂 目录结构解析)
  • [📌 每个模块的作用 + 示例代码](#📌 每个模块的作用 + 示例代码)
  • • [1. `/api` ------ 接口封装](#1. /api —— 接口封装)
    • [2. `/utils` ------ 工具函数](#2. /utils —— 工具函数)
    • [3. `/store` ------ 全局状态（Pinia）](#3. /store —— 全局状态（Pinia）)
    • [4. `/components` ------ 公共组件](#4. /components —— 公共组件)
    • [5. `/composables` ------ 自定义 hooks](#5. /composables —— 自定义 hooks)
    • [6. `/pages` ------ 页面目录](#6. /pages —— 页面目录)
    • [7. `/styles` ------ 全局样式](#7. /styles —— 全局样式)
    • [8. `/types` ------ 类型定义](#8. /types —— 类型定义)
    • [9. `main.ts` ------ 入口文件](#9. main.ts —— 入口文件)
    • [10. `App.vue` ------ 根组件](#10. App.vue —— 根组件)
    • [11. `manifest.json`](#11. manifest.json)
    • [12. `pages.json`](#12. pages.json)
    • [13. `uni.scss`](#13. uni.scss)
  • [🔄 串联起来的流程（箭头版）](#🔄 串联起来的流程（箭头版）)
  • 总结

uni-app Vue 项目的规范目录结构全解

引言

想象一下，如果你要盖一栋楼：

• 你需要图纸（架构）
• 你需要水泥和钢材（工具函数、组件）
• 你需要电、水、管道系统（接口、路由、状态管理）

如果一切都堆在一起，现场就是个「大工地」，乱七八糟难以维护。

这就是为什么我们需要一个清晰的项目目录结构。

首先，你需要去uniapp官方网站去安装一个基本目录：uniapp官方网站。注意：不管你是通过命令或是下载安装包的形式他都是一个最基本的目录（在真实项目中肯定是对其做以下扩展的）。我们接下来提到的文件功能模块更多的是要自己新建的，可以做到更多的模块化，让项目目录更加规范。

下面，我就带你逐个认识 /src 里的每个「部门」，让你理解它们各自的职责。

---

📂 目录结构解析

文件/文件夹	作用	解决了什么问题
/api	接口封装层	避免每次都手写 uni.request，统一管理请求
/assets	静态资源	存放图片、字体、icon，让资源集中管理
/components	通用组件	封装按钮、导航栏等公共模块，避免重复写代码
/composables	自定义 hooks	抽离逻辑复用，比如登录检测、主题切换
/pages	业务页面	每个页面就是一个独立功能模块
/router	路由配置	管理页面跳转，解耦 pages.json
/store	状态管理（Pinia）	全局数据共享，比如用户信息、token
/utils	工具函数库	封装格式化、加解密、校验等小工具
/styles	全局样式	存放主题色、通用 CSS，让全局风格统一
/types	TS 类型定义	定义接口、数据结构，增强代码可维护性
main.ts	项目入口	挂载 App，初始化插件
App.vue	根组件	整个应用的"壳子"
manifest.json	App 配置	应用的基本信息（小程序配置、权限等）
pages.json	页面路由表	配置页面路径、导航栏等
uni.scss	全局样式变量	定义全局样式变量，比如颜色、字体大小

---

📌 每个模块的作用 + 示例代码

1. /api ------ 接口封装

作用：把 uni.request 封装成统一的调用方式，避免重复写请求逻辑。

// /src/api/user.ts
import request from "@/utils/request"

// 获取用户信息
export function getUserInfo() {
  return request({
    url: "/user/info",
    method: "GET"
  })
}

// 登录接口
export function login(data: { username: string; password: string }) {
  return request({
    url: "/auth/login",
    method: "POST",
    data
  })
}

---

2. /utils ------ 工具函数

作用：抽离通用的小功能，比如请求封装、日期格式化。

// /src/utils/request.ts
export default function request(options: UniApp.RequestOptions) {
  return new Promise((resolve, reject) => {
    uni.request({
      ...options,
      header: {
        Authorization: uni.getStorageSync("token") || "",
        ...options.header,
      },
      success: (res) => resolve(res.data),
      fail: (err) => reject(err),
    })
  })
}

---

3. /store ------ 全局状态（Pinia）

作用：存放用户信息、登录状态，任何页面都能访问。

// /src/store/user.ts
import { defineStore } from "pinia"

export const useUserStore = defineStore("user", {
  state: () => ({
    token: "",
    userInfo: null as null | { name: string; avatar: string }
  }),
  actions: {
    setToken(token: string) {
      this.token = token
      uni.setStorageSync("token", token)
    },
    setUserInfo(info: any) {
      this.userInfo = info
    }
  }
})

---

4. /components ------ 公共组件

作用：把常用 UI 提炼出来，方便复用。

<!-- /src/components/BaseButton.vue -->
<template>
  <button class="btn" @click="$emit('click')">
    <slot></slot>
  </button>
</template>

<style scoped>
.btn {
  padding: 10px 20px;
  background: var(--primary-color, #42b983);
  color: #fff;
  border-radius: 6px;
}
</style>

---

5. /composables ------ 自定义 hooks

作用：逻辑复用，例如主题切换。

// /src/composables/useTheme.ts
import { ref } from "vue"

const theme = ref<"light" | "dark">("light")

export function useTheme() {
  function toggleTheme() {
    theme.value = theme.value === "light" ? "dark" : "light"
    document.documentElement.className = `${theme.value}-theme`
  }
  return { theme, toggleTheme }
}

---

6. /pages ------ 页面目录

作用：一个页面一个文件夹，业务逻辑更清晰。

/pages
  /home
    index.vue
  /login
    index.vue
<!-- /src/pages/home/index.vue -->
<template>
  <view>
    <BaseButton @click="loadUser">获取用户信息</BaseButton>
    <view v-if="user">{{ user.name }}</view>
  </view>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { getUserInfo } from "@/api/user"
import BaseButton from "@/components/BaseButton.vue"

const user = ref<any>(null)
function loadUser() {
  getUserInfo().then(res => user.value = res)
}
</script>

---

7. /styles ------ 全局样式

作用：统一主题。

/* /src/styles/variables.scss */
$primary-color: #42b983;
$text-color: #333;

---

8. /types ------ 类型定义

作用：让接口数据结构更清晰。

// /src/types/user.ts
export interface User {
  id: number
  name: string
  avatar: string
}

---

9. main.ts ------ 入口文件

作用：挂载应用、注册插件。

// /src/main.ts
import { createSSRApp } from "vue"
import { createPinia } from "pinia"
import App from "./App.vue"

export function createApp() {
  const app = createSSRApp(App)
  app.use(createPinia()) // 挂载全局 store
  return { app }
}

---

10. App.vue ------ 根组件

作用：定义全局结构。

<template>
  <slot />
</template>

<script setup>
// 可以在这里定义全局逻辑，比如主题
</script>

---

11. manifest.json

作用：小程序/应用的配置，比如名字、appid、权限。

---

12. pages.json

作用：页面路由表。

{
  "pages": [
    {
      "path": "pages/home/index",
      "style": { "navigationBarTitleText": "首页" }
    },
    {
      "path": "pages/login/index",
      "style": { "navigationBarTitleText": "登录" }
    }
  ]
}

---

13. uni.scss

作用：全局样式变量。

/* /src/uni.scss */
$uni-primary: #42b983;

---

🔄 串联起来的流程（箭头版）

main.ts (入口挂载)
   ↓
App.vue (根组件)
   ↓
pages.json (页面配置)
   ↓
store (全局状态) ←→ api (接口) ←→ utils (工具)
   ↓
pages (页面使用组件 & hooks)
   ↓
components (通用组件)
   ↓
styles / types (全局样式 & 类型)

---

总结

这个目录结构就像是一座「现代工厂」：

• /api 是流水线接口
• /components 是零件库
• /composables 是工人的操作手册
• /pages 是产品车间
• /store 是仓库
• /utils 是工具箱
• /styles 是装修设计
• /types 是产品说明书

掌握这些模块，你就能快速把一个 uni-app Vue 项目「从工地搭建成高楼大厦」。