Uni-App（Vue3 + TypeScript）项目结构详解 ------ 以 Lighting-UniApp 为例，提供源代码
Uni-App（Vue3 + TypeScript）项目源代码在最后
在本文中，我们将详细解析一个完整的 Uni-App + Vue3 + TypeScript
工程结构。 以项目 Lighting-UniApp
为示例，带你了解每个文件、目录的用途与作用。
📁 项目结构总览
LIGHTING-UNIAPP/
├─ .idea/ # VSCode / WebStorm 项目配置文件
├─ dist/ # 打包输出目录（编译后的文件）
├─ node_modules/ # 第三方依赖库（由 npm 自动生成）
├─ src/ # 核心源代码目录
│ ├─ api/ # 与后端通信的接口封装
│ ├─ components/ # 自定义 Vue 组件
│ ├─ hooks/ # 封装的组合式函数（Composition API）
│ ├─ pages/ # 应用页面（每个文件夹代表一个页面）
│ ├─ static/ # 静态资源（图片、音频、字体等）
│ ├─ store/ # 全局状态管理（Pinia 或 Vuex）
│ ├─ utils/ # 工具函数模块（时间格式化、节流、防抖等）
│ ├─ App.vue # 应用根组件
│ ├─ env.d.ts # 环境类型声明文件（用于全局类型补充）
│ ├─ main.ts # 应用入口文件（创建 Vue 应用实例）
│ └─ manifest.json # Uni-App 运行配置文件（App 权限、启动图等）
│
├─ pages.json # 页面配置文件（页面路径与导航栏）
├─ shime-uni.d.ts # Uni-App 全局类型声明文件（为 `uni.*` 提供类型提示）
├─ uni.scss # 全局样式变量文件（颜色、字体、间距）
├─ .gitignore # Git 忽略文件列表
├─ eslint.config.mjs # ESLint 代码规范配置
├─ index.html # Web 平台入口 HTML 文件（H5 编译时使用）
├─ package-lock.json # npm 依赖锁定文件（自动生成）
├─ package.json # 项目信息与依赖声明（最核心的配置）
├─ README.md # 项目说明文档
├─ shims-uni.d.ts # 兼容不同平台的 Uni 类型声明
├─ tsconfig.json # TypeScript 编译配置文件
└─ vite.config.ts # Vite 构建工具配置文件
🧩 各目录与文件详解
1️⃣ .idea/
由 JetBrains（WebStorm、PhpStorm）自动生成，保存 IDE
工程设置，不参与构建。
2️⃣ dist/
项目打包后生成的产物目录。
通常不会手动编辑，发布或部署时使用。
3️⃣ node_modules/
项目依赖安装后生成的模块目录，包含所有 npm 包。
4️⃣ src/ ------ 项目核心代码目录
📁 api/
用于封装与后端通信的接口模块，示例：
import request from '@/utils/request'export const getUserList = () => request.get('/user/list')
📁 components/
放置全局或局部可复用的 Vue 组件，例如：
<MyButton />
<UserCard />
📁 hooks/
自定义组合式函数目录，用于抽离通用逻辑：
export function useCounter() {const count = ref(0)const increment = () => count.value++return { count, increment }
}
📁 pages/
每个文件夹代表一个独立页面，例如：
pages/
├─ index/
│ └─ index.vue
├─ login/
│ └─ login.vue
📁 static/
放置不会被 Webpack/Vite 处理的静态资源（如图片、音频）。
📁 store/
用于状态管理，可采用 Pinia：
import { defineStore } from 'pinia'export const useUserStore = defineStore('user', {state: () => ({ name: '张三', token: '' })
})
📁 utils/
封装项目常用工具函数：
export function formatTime(date: Date) {return date.toLocaleString()
}
🧩 App.vue
应用根组件，是整个项目的启动入口（类似 React 的 App.js）。
🧩 main.ts
项目启动文件，挂载 App 并创建应用实例：
import { createSSRApp } from 'vue'
import App from './App.vue'export function createApp() {const app = createSSRApp(App)return { app }
}
🧩 manifest.json
App 端运行配置文件，控制应用图标、启动页、权限等。
5️⃣ pages.json
定义页面路径与导航栏外观，是 UniApp 的"路由表"。
{"pages": [{"path": "pages/index/index","style": { "navigationBarTitleText": "首页" }}]
}
6️⃣ uni.scss
全局样式变量文件，例如：
$primary-color: #3b82f6;
$text-color: #333;
所有 .vue 页面都可直接使用这些变量。
7️⃣ vite.config.ts
Vite 构建配置文件，定义插件与路径别名：
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { fileURLToPath, URL } from 'node:url'export default defineConfig({resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },plugins: [uni()]
})
8️⃣ tsconfig.json
TypeScript 的核心配置文件，控制类型检查、语法支持和路径解析：
{"compilerOptions": {"target": "ESNext","strict": true,"baseUrl": ".","paths": { "@/*": ["./src/*"] }}
}
9️⃣ .eslintrc.cjs / eslint.config.mjs
代码规范配置文件，控制 ESLint 行为，比如是否允许多余空格、未使用变量等。
🔟 其他文件说明
文件 说明
.gitignore 控制哪些文件不提交到 Git
index.html H5 运行入口
package.json 项目依赖、脚本命令
package-lock.json 锁定依赖版本
README.md 项目说明文档
shims-uni.d.ts / env.d.ts 提供 UniApp、环境变量的类型声明
📘 路由封装（和vue用法一致）
该路由系统基于 Uni-App 与 Vue3 构建，统一封装了页面跳转与参数管理逻辑。
它自动解析 URL 中的参数（支持多层 JSON 与编码），并提供类型安全的路由对象。
开发者通过 useRouter() 即可在任意页面中获取参数、执行跳转、重定向或返回，简化页面通信与导航流程。
分别负责 URL 拼接 → 参数传递 → 参数解析 → 页面 Hook
🧱 基础工具 utils/params.ts 负责把参数对象拼接或解析成 URL
🧭 路由核心类 utils/router.ts 封装 uni.navigateTo / redirectTo 等操作
🔍 参数解析Hook useQuery/index.ts 负责在页面加载时解析 URL 参数并返回响应式对象
🔗 路由Hook useRouter/index.ts 将 Router 与 useQuery 结合，实现页面级路由对象
🧱 1️⃣ params.ts —— URL 参数工具
功能：拼接或解析 URL 参数。提供函数：setParams(url, params)：把对象转成 ?a=1&b=2。getParams(url)：从 URL 提取参数对象。服务对象：被 router.ts 调用，用来生成跳转链接。
🧭 2️⃣ router.ts —— 路由核心类
功能：封装 uni.navigateTo、redirectTo、switchTab、back。核心点：统一参数处理（调用 setParams() 拼接）。维护当前 path 与 query。提供生命周期回调 ready() / runReady()。服务对象：被 useRouter.ts 实例化，用来操作页面跳转。
🔍 3️⃣ useQuery —— 参数解析 Hook
功能：在页面加载时自动解析 URL 参数。特性：两次 decodeURIComponent 解码。自动识别 JSON 并递归解析。支持合并默认值。输出：返回响应式对象 query。服务对象：被 useRouter.ts 调用，用于读取当前页参数。
🔗 4️⃣ useRouter —— 页面路由 Hook（整合层）
功能：把 Router + useQuery 结合成页面可直接使用的路由对象。逻辑：创建 query = useQuery()；创建响应式 router = new Router()；在 onLoad 时写入 query 和当前路径；页面渲染完成后执行 router.runReady() 回调。输出：一个带跳转功能、含当前参数的 router 实例。
🔄 四者协作流程
页面加载↓useRouter()├─ 调用 useQuery() → 解析 URL 参数├─ 创建 Router() → 管理跳转与状态├─ 写入 query/path└─ nextTick → runReady() 触发回调
✅ 一句话总结：
params.ts 负责拼接，router.ts 负责跳转，
useQuery 负责解析，useRouter 负责整合。
页面通过 useRouter() 一步即可完成「参数解析 + 路由操作」。
📘 总结
Lighting-UniApp 是一个基于 Vue3 + TypeScript + Uni-App
的跨平台项目， 通过 vite 构建、tsconfig.json
提供类型支持、pages.json 控制页面结构、manifest.json 管理应用权限。
这一结构清晰、模块划分明确的项目架构，非常适合前端工程化与移动端多端开发。
✨ 作者建议：写项目时，保持
api、store、utils的独立性；保持
pages.json的整洁，可以让你的 UniApp 项目结构清晰、易维护。
源代码
https://gitee.com/yinerjie/uniapp_vue3_ts.git