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

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

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 = tokenuni.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/homeindex.vue/loginindex.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: numbername: stringavatar: 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()) // 挂载全局 storereturn { 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 项目「从工地搭建成高楼大厦」。