【已開源】UniApp+vue3跨端應用從0到1開發指南、uniapp+vue3模板應用

在跨端開發日益成為主流的今天，如何高效構建規范、可維護的企業級應用？本文以UniApp+Vue3+* *TypeScript**為核心技術棧，手把手帶你從零搭建高標準的跨平臺項目。

通過本文，你將系統掌握：

? 環境配置：Node版本管理、Vite腳手架初始化、Vue3+TS工程化配置
? 開發規范：ESLint+Prettier+Stylelint三劍客整合，Git提交自動化與Commitizen規范化
? 進階實戰：Pinia全局狀態管理、UnoCSS原子化樣式、HTTP請求封裝與反向代理實戰
? 工程擴展：UI庫深度整合（uView-plus/wot-design-uni）、按需自動導入、多環境變量策略
? 跨端適配：H5/小程序多平臺編譯與Nginx部署方案，破解跨域難題

無論你是初探UniApp生態，還是希望升級現有項目的工程化水平，本文都將提供從環境搭建到生產部署的全鏈路指南，助你打造高性能、高規范、跨端兼容的現代Web應用。代碼即規范，開箱即用，開啟高效開發之旅！

Gitee開源地址： https://gitee.com/moxunjinmu/uniapp-vue3-template

Github開源地址：https://github.com/moxunjinmu/uniapp-vue3-template

如果對你有點用的話歡迎Star???，拜托啦~

一、環境準備

安裝Node.js（推薦nvm安裝管理node版本）

👉 NVM (Node Version Manager) 是一個用于管理多個 Node.js 版本的工具，便于在不同項目間切換 Node 環境

詳細安裝教程：莫循躍遷：nvm管理node版本速通👉 nvm（Node Version Manager）是一個用于管理Node.js - 掘金

配置效果

請添加圖片描述

安裝完成后，可以通過以下命令驗證：

nvm -v

注意事項

推薦使用 Node.js 16.x 或更高版本
在 Windows 系統中，可能需要以管理員身份運行命令提示符

安裝開發工具

安裝VScode

👉 Visual Studio Code 是微軟開發的輕量級代碼編輯器，支持多種編程語言和豐富的插件擴展

下載地址：https://code.visualstudio.com/

或者安裝cursor

👉 Cursor 是一款基于 AI 的代碼編輯器，提供智能代碼補全和建議功能

詳細安裝教程：《AI編程開發微信小程序》第一章：AI自動化編程神器Cursor基礎使用教程嗨，大家好，我是莫循，一個用AI加速開發的 - 掘金

安裝Vue CLI

👉 Vue CLI 是 Vue.js 官方提供的項目腳手架工具，用于快速創建和配置 Vue 項目

全局安裝

npm install -g @vue/cli  # 默認安裝最新版

權限問題：

Windows：以管理員身份運行 CMD 或 PowerShell
Linux/Mac：添加 sudo 前綴（sudo npm install -g @vue/cli）

驗證安裝

vue --version  # 顯示版本號如 @vue/cli 5.0.8

常見錯誤：

'vue' 不是內部命令：檢查環境變量是否包含 npm 全局路徑（默認：C:\Users<用戶>\AppData\Roaming\npm）
版本過低：通過 npm update -g @vue/cli 升級

二、創建項目

初始化項目

👉 按照 uni-app 官方文檔的步驟，通過 vue-cli 創建 uni-app + vue + typescript 腳手架：

npx degit dcloudio/uni-preset-vue#vite-ts uniapp-vue3-template

請添加圖片描述

?? 如果使用命令創建失敗，可以通過 Gitee 下載 ZIP 包：vite-ts 分支。

配置`TypeScript`編譯器

👉 TypeScript 編譯器配置文件決定了代碼的編譯規則和類型檢查行為

默認生成的 TypeScript編譯器配置文件 tsconfig.json 中繼承的 @vue/tsconfig/tsconfig.json 文件不存在。因此，你需要移除此繼承配置并添加相應的編譯設置。

請添加圖片描述

根據 TypeScript 官方配置文檔，調整后的完整配置如下：

{"compilerOptions": {"module": "esnext","moduleResolution": "node","target": "esnext","allowJs": true,"skipLibCheck": true,"strict": true,
?"sourceMap": true,"baseUrl": ".","paths": {"@/*": ["./src/*"]},"lib": ["esnext", "dom"],"types": ["@dcloudio/types", "vue"]},"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],"exclude": ["node_modules", "dist"]
}

正確配置后，TypeScript 編譯器將能夠：

識別 @/* 路徑別名
提供 Vue 和 uni-app 的類型支持
對項目中的 .ts 和 .vue 文件進行類型檢查注意事項
確保 types 數組中包含 @dcloudio/types 和 vue ，以獲得完整的類型支持
如果遇到類型錯誤，可能需要安裝相應的類型定義包： npm install --save-dev @dcloudio/types @vue/runtime-core

三、核心配置

代碼規范配置

配置ESLint

👉 ESLint 是一個靜態代碼分析工具，用于識別和報告 JavaScript/TypeScript 代碼中的問題

VSCode 插件市場搜索 ESLint 插件并安裝

安裝插件

VSCode 插件市場搜索 ESLint 插件并安裝

請添加圖片描述

通過以下命令快速生成 ESLint 配置文件：

npx eslint --init

配置過程

PS D:\700-code\750-Gitee\uniapp-vue3-template> npx eslint --init
You can also run this command directly using 'npm init @eslint/config@latest'.
@eslint/create-config: v1.6.0
?
√ How would you like to use ESLint? · problems    
√ What type of modules does your project use? · esm
√ Which framework does your project use? · vue
√ What type of modules does your project use? · esm
√ What type of modules does your project use? · esm
√ Which framework does your project use? · vue
√ What type of modules does your project use? · esm
√ What type of modules does your project use? · esm
√ Which framework does your project use? · vue
√ Does your project use TypeScript? · typescript
√ Does your project use TypeScript? · typescript
√ Where does your code run? · browser
√ Where does your code run? · browser
The config that you've selected requires the following dependencies:
The config that you've selected requires the following dependencies:
?
?
eslint, globals, @eslint/js, typescript-eslint, eslint-plugin-vue
eslint, globals, @eslint/js, typescript-eslint, eslint-plugin-vue
√ Would you like to install them now? · No / Yes
√ Would you like to install them now? · No / Yes
√ Which package manager do you want to use? · pnpm
√ Which package manager do you want to use? · pnpm
??Installing...
??Installing...WARN? 7 deprecated subdependencies found: abab@2.0.6, domexception@2.0.1, glob@7.2.3, inflight@1.0.6, phin@2.9.3, rimraf@3.0.2, w3c-hr-time@1.0.2
Packages: +72
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 863, reused 790, downloaded 32, added 72, doneWARN? Issues with peer dependencies found
.
└─┬ @dcloudio/uni-automator 3.0.0-4030620241128001└─┬ @dcloudio/uni-cli-shared 3.0.0-4030620241128001└─┬ @vue/server-renderer 3.4.21└── ? unmet peer vue@3.4.21: found 3.5.13
?
?
devDependencies:
+ @eslint/js 9.23.0
+ eslint 9.23.0
+ eslint-plugin-vue 10.0.0
+ globals 16.0.0
+ typescript-eslint 8.27.0
?
Done in 6.1s
Done in 6.1s
Successfully created D:\700-code\750-Gitee\uniapp-vue3-template\eslint.config.mjs file.

執行該命令后，ESLint 會通過交互式問題的方式，幫助生成配置文件。針對 9.x 版本，默認會生成基于 Flat Config 格式的 eslint.config.mjs 文件，與之前的 .eslintrc 格式有所不同。

默認生成的 eslint.config.mjs 文件如下所示：

請添加圖片描述

在此基礎上，可以根據項目的需求進行一些定制化配置，例如添加忽略規則或自定義的特殊規則。

import globals from "globals"; // 全局變量配置
import pluginJs from "@eslint/js"; // JavaScript 的推薦配置
import tseslint from "typescript-eslint"; // TypeScript 配置
import pluginVue from "eslint-plugin-vue"; // Vue 配置
?
export default [{files: ["**/*.{js,mjs,cjs,ts,vue}"]}, // 校驗的文件類型{languageOptions: { globals: {...globals.browser , ...globals.node} }}, // 瀏覽器/Node環境全局變量pluginJs.configs.recommended, // JavaScript 推薦配置...tseslint.configs.recommended, // TypeScript 推薦配置...pluginVue.configs["flat/essential"], // Vue 推薦配置{ files: ["**/*.vue"], languageOptions: { parserOptions: { parser: tseslint.parser } } }, // 對 .vue 文件使用 TypeScript 解析器// 添加忽略的文件或目錄{ignores: ["/dist","/public","/node_modules","**/*.min.js","**/*.config.mjs","**/*.tsbuildinfo","/src/manifest.json",]},
?// 自定義規則{rules: {quotes: ["error", "double"], // 強制使用雙引號"quote-props": ["error", "always"], // 強制對象的屬性名使用引號semi: ["error", "always"], // 要求使用分號indent: ["error", 2], // 使用兩個空格進行縮進"no-multiple-empty-lines": ["error", { max: 1 }], // 不允許多個空行"no-trailing-spaces": "error", // 不允許行尾有空格
?// TypeScript 規則"@typescript-eslint/no-explicit-any": "off", // 禁用 no-explicit-any 規則，允許使用 any 類型"@typescript-eslint/explicit-function-return-type": "off", // 不強制要求函數必須明確返回類型"@typescript-eslint/no-empty-interface": "off", // 禁用 no-empty-interface 規則，允許空接口聲明"@typescript-eslint/no-empty-object-type": "off", // 允許空對象類型
?// Vue 規則"vue/multi-word-component-names": "off", // 關閉多單詞組件名稱的限制"vue/html-indent": ["error", 2], // Vue 模板中的 HTML 縮進使用兩個空格"vue/no-v-html": "off", // 允許使用 v-html (根據實際項目需要)},},
];

添加 ESLint 腳本

👉 在 package.json 中添加 lint 命令，方便執行代碼檢查

為了方便使用 ESLint，可以在 package.json 中添加 lint 腳本命令：

{"scripts": {"lint:eslint": "eslint --fix ./src","lint": "npm run lint:eslint"}
}

此腳本會自動修復符合 ESLint 規則的代碼問題，并輸出檢查結果。

測試效果

在 App.vue 文件中聲明一個未使用的變量，并運行 pnpm run lint，可以看到 ESLint 提示該變量未使用。如下圖所示：

請添加圖片描述

這里多報了一個錯誤顯示 ‘@typescript-eslint/ban-types’ was not found，查找解決方法，需要安裝依賴。我們執行下方命令：

> npm install --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser

重新執行pnpm run lint ，結果：

請添加圖片描述

安裝解析器

👉 vue-eslint-parser 是專門用于解析 .vue 文件的 ESLint 解析器

pnpm install vue-eslint-parser --save-dev

請添加圖片描述

針對不同文件配置插件和解析器：

// eslint.config.mjs
import globals from "globals";
import js from "@eslint/js";
?
// ESLint 核心插件
import pluginVue from "eslint-plugin-vue";
import pluginTypeScript from "@typescript-eslint/eslint-plugin";
?
// Prettier 插件及配置
import configPrettier from "eslint-config-prettier";
import pluginPrettier from "eslint-plugin-prettier";
?
// 解析器
import * as parserVue from "vue-eslint-parser";
import * as parserTypeScript from "@typescript-eslint/parser";
?
// 定義 ESLint 配置
export default [// 通用 JavaScript/TypeScript 配置{...js.configs.recommended,ignores: ["/dist","/public","/node_modules","**/*.min.js","**/*.config.mjs","**/*.tsbuildinfo","/src/manifest.json",],languageOptions: {globals: {...globals.browser, // 瀏覽器變量 (window, document 等)...globals.node, // Node.js 變量 (process, require 等)},},plugins: {prettier: pluginPrettier,},rules: {...configPrettier.rules,...pluginPrettier.configs.recommended.rules,"no-debug": "off", // 允許使用 debugger"prettier/prettier": ["error",{endOfLine: "auto", // 解決換行符沖突},],},},
?// TypeScript 配置{files: ["**/*.?([cm])ts"],languageOptions: {parser: parserTypeScript,parserOptions: {sourceType: "module",},},plugins: {"@typescript-eslint": pluginTypeScript,},rules: {...pluginTypeScript.configs.recommended.rules,"@typescript-eslint/no-explicit-any": "off", // 允許使用 any"@typescript-eslint/no-empty-function": "off", // 允許空函數"@typescript-eslint/no-empty-object-type": "off", // 允許空對象類型"@typescript-eslint/consistent-type-imports": ["error",{ disallowTypeAnnotations: false, fixStyle: "inline-type-imports" },], // 統一類型導入風格},},
?// TypeScript 聲明文件的特殊配置{files: ["**/*.d.ts"],rules: {"eslint-comments/no-unlimited-disable": "off", // 關閉 eslint 注釋相關規則"unused-imports/no-unused-vars": "off", // 忽略未使用的導入},},
?// JavaScript (commonjs) 配置{files: ["**/*.?([cm])js"],rules: {"@typescript-eslint/no-var-requires": "off", // 允許 require},},
?// Vue 文件配置{files: ["**/*.vue"],languageOptions: {parser: parserVue,parserOptions: {parser: "@typescript-eslint/parser",sourceType: "module",},},plugins: {vue: pluginVue,},processor: pluginVue.processors[".vue"],rules: {...pluginVue.configs["vue3-recommended"].rules,"vue/no-v-html": "off", // 允許 v-html"vue/require-default-prop": "off", // 允許沒有默認值的 prop"vue/multi-word-component-names": "off", // 關閉組件名稱多詞要求"vue/html-self-closing": ["error",{html: { void: "always", normal: "always", component: "always" },svg: "always",math: "always",},], // 自閉合標簽},},
];

集成 Prettier

👉 Prettier 是一個代碼格式化工具，可以強制執行一致的代碼風格

prettier 中文網：https://prettier.nodejs.cn/

安裝插件

VSCode 插件市場搜索 Prettier - Code formatter 插件安裝

請添加圖片描述

安裝依賴

pnpm install -D prettier eslint-config-prettier eslint-plugin-prettier

請添加圖片描述

prettier：主要的 Prettier 格式化庫。
eslint-plugin-prettier：將 Prettier 的規則作為 ESLint 的規則來運行。
eslint-config-prettier：禁用所有與格式相關的 ESLint 規則，以避免和 Prettier 的沖突。

配置 Prettier

👉 以下是 Prettier 配置文件，定義了代碼格式化的規則

項目根目錄下新建配置文件 prettier.config.mjs，添加常用規則：

export default {printWidth: 100, // 每行最多字符數量，超出換行(默認80)tabWidth: 2, // 縮進空格數，默認2個空格useTabs: false, // 指定縮進方式，空格或tab，默認false，即使用空格semi: true, // 使用分號singleQuote: false, // 使用單引號 (true:單引號;false:雙引號)trailingComma: 'all', // 末尾使用逗號
};

配置忽略文件

項目根目錄新建 .prettierignore 文件指定 Prettier 不需要格式化的文件和文件夾

.prettierignore
node_modules
dist
public
*.min.js

添加格式化腳本

在 package.json 文件中添加：

{"scripts": {"format": "prettier --write ./src"}
}

請添加圖片描述

保存自動格式化

打開 VSCode 的 File → Preferences → Settings，然后選擇 Open Settings (JSON)，添加以下配置

{"editor.formatOnSave": true, // 保存格式化文件"editor.defaultFormatter": "esbenp.prettier-vscode" // 指定 prettier 為所有文件默認格式化器
}

集成 Stylelint

👉 Stylelint 一個強大的 CSS linter(檢查器)，可幫助您避免錯誤并強制執行約定。

Stylelint 官網：https://stylelint.io/

安裝插件

VSCode 插件搜索 Stylelint 并安裝

請添加圖片描述

安裝依賴

pnpm install -D postcss postcss-html postcss-scss stylelint stylelint-config-recommended stylelint-config-recommended-scss stylelint-config-recommended-vue stylelint-config-recess-order stylelint-config-html stylelint-prettier

表格還在加載中，請等待加載完成后再嘗試復制

配置 Stylelint

根目錄新建 .stylelintrc.cjs 文件，配置如下：

module.exports = {extends: ["stylelint-config-recommended","stylelint-config-recommended-scss","stylelint-config-recommended-vue/scss","stylelint-config-html/vue","stylelint-config-recess-order"],plugins: ["stylelint-prettier"],overrides: [{files: ["**/*.{vue,html}"],customSyntax: "postcss-html"},{files: ["**/*.{css,scss}"],customSyntax: "postcss-scss"}],rules: {"import-notation": "string","selector-class-pattern": null,"custom-property-pattern": null,"keyframes-name-pattern": null,"no-descending-specificity": null,"no-empty-source": null,"selector-pseudo-class-no-unknown": [true,{ignorePseudoClasses: ["global", "export", "deep"]}],"unit-no-unknown": [true, {ignoreUnits: ["rpx"]}],"property-no-unknown": [true,{ignoreProperties: []}],"at-rule-no-unknown": [true,{ignoreAtRules: ["apply", "use", "forward"]}]}
};

配置忽略文件

根目錄創建 .stylelintignore 文件，配置忽略文件如下：

*.min.js
dist
public
node_modules

添加 Stylelint 腳本

package.json 添加 Stylelint 檢測指令：

  "scripts": {"lint:stylelint": "stylelint  "**/*.{css,scss,vue,html}" --fix"}

保存自動修復

項目根目錄下.vscode/settings.json 文件添加配置：

{"editor.codeActionsOnSave": {"source.fixAll.stylelint": true },"stylelint.validate": ["css", "scss", "vue", "html"]
}

為了驗證把尺寸屬性 width 放置在定位屬性 position 前面，根據 CSS 書寫順序規范推斷是不符合規范的，在保存時 Stylelint 自動將屬性重新排序，達到預期。

測試

執行以下命令進行檢測

npm run lint:stylelint

Git提交規范配置

👉 配置 Husky 的 pre-commit 和 commit-msg 鉤子，實現代碼提交的自動化檢查和規范化。

pre-commit: 使用 Husky + Lint-staged，在提交前進行代碼規范檢測和格式化。確保項目已配置 ESLint、Prettier 和 Stylelint。
commit-msg: 結合 Husky、Commitlint、Commitizen 和 cz-git，生成規范化且自定義的 Git commit 信息。

集成 Husky

👉 Husky 是 Git 鉤子工具，可以設置在 git 各個階段（pre-commit、commit-msg 等）觸發。

Husky官網：https://typicode.github.io

請添加圖片描述

安裝依賴

pnpm add -D husky

初始化

init 命令簡化了項目中的 husky 設置。它會在 .husky/ 中創建 pre-commit 腳本，并更新 package.json 中的 prepare 腳本。

pnpm exec husky init

默認生成了 pnpm test ,改成 echo "Running pre-commit hook..."測試功能

echo "Running pre-commit hook..."

測試

請添加圖片描述

通過 pre-commit 鉤子，可以自動運行各種代碼檢查工具，在提交代碼前強制執行代碼質量和樣式檢查。常見的工具包括：

eslint：用于檢查和修復 JavaScript/TypeScript 代碼中的問題。
stylelint：用于檢測和修復 CSS/SCSS 樣式問題。

接下來，集成 lint-staged 和 commitlint 來進一步完善開發體驗。

集成 lint-staged

👉 lint-staged 是一個工具，專門用于只對 Git 暫存區的文件運行 lint 或其他任務，確保只檢查和修復被修改或新增的代碼部分，而不會影響整個代碼庫。這樣可以顯著提升效率，尤其是對于大型項目。

安裝依賴

使用以下命令安裝 lint-staged：

pnpm add -D lint-staged

配置 lint-staged

在 package.json 中添加 lint-staged 配置，確保在 pre-commit 階段自動檢測暫存的文件：

{"name": "vue-uniapp-template","version": "0.0.0","lint-staged": {"*.{js,ts}": ["eslint --fix","prettier --write"],"*.{cjs,json}": ["prettier --write"],"*.{vue,html}": ["eslint --fix","prettier --write","stylelint --fix"],"*.{scss,css}": ["stylelint --fix","prettier --write"],"*.md": ["prettier --write"]}
}

在 package.json 的 scripts 部分中，添加用于運行 lint-staged 的命令：

"scripts": {"lint:lint-staged": "lint-staged"
}

添加 Husky 鉤子

在項目根目錄的 .husky/pre-commit 中添加以下命令，確保在提交代碼前執行 lint-staged：

pnpm run lint:lint-staged

測試

提交代碼時，lint-staged 會自動對暫存的文件運行相應的 lint 任務。

請添加圖片描述

通過這種集成方式，確保代碼在提交前經過自動格式化和校驗，提高代碼質量和一致性。

集成 Commitlint

👉 commitlint 用于檢查 Git 提交信息是否符合特定規范（如 Angular 提交規范），從而保證提交信息的一致性。

Commitlint官網：https://commitlint.js.org/

安裝依賴

pnpm add -D  @commitlint/cli @commitlint/config-conventional

配置 Commitlint

在項目根目錄下創建 commitlint.config.cjs 文件，添加以下內容來啟用 Angular 規范：

module.exports = {// 繼承的規則extends: ["@commitlint/config-conventional"],// 自定義規則rules: {// 提交類型枚舉，git提交type必須是以下類型 @see https://commitlint.js.org/#/reference-rules"type-enum": [2,"always",["feat", // 新增功能"fix", // 修復缺陷"docs", // 文檔變更"style", // 代碼格式（不影響功能，例如空格、分號等格式修正）"refactor", // 代碼重構（不包括 bug 修復、功能新增）"perf", // 性能優化"test", // 添加疏漏測試或已有測試改動"build", // 構建流程、外部依賴變更（如升級 npm 包、修改 webpack 配置等）"ci", // 修改 CI 配置、腳本"revert", // 回滾 commit"chore", // 對構建過程或輔助工具和庫的更改（不影響源文件、測試用例）],],"subject-case": [0], // subject大小寫不做校驗},
};

添加 Husky 鉤子

將 commitlint 與 Husky 集成，在 .husky/commit-msg 文件中添加以下內容，確保提交信息符合規范：

npx --no-install commitlint --edit $1

測試

根據 Angular 的提交規范，提交信息由以下部分組成：

類型：表示本次提交的類型，例如 feat (新功能)、fix (修復 bug)、docs (文檔更新)。
作用域（可選）：說明本次提交影響的模塊，例如 auth、ui。
簡短描述：簡潔明了的提交描述，限定在 50 字符以內。

當你嘗試提交不符合規范的提交信息時，提交會被阻止，并顯示相關錯誤提示。如下圖所示：

請添加圖片描述

集成 Commitizen 和 cz-git

commitizen: 是一個幫助開發者以標準化格式生成提交信息的工具。–Commitizen 官方文檔
cz-git: cz-git 是 Commitizen 的適配器之一，它基于 Commitizen，提供了更多自定義功能和增強的交互體驗。–cz-git 官方文檔

安裝依賴

配置 cz-git

在項目中初始化 Commitizen，并配置使用 cz-git 作為適配器。在 package.json 中添加以下配置：

"config": {"commitizen": {"path": "node_modules/cz-git"}
}

在commitlint 的配置文件 commitlint.config.cjs 中添加配置，commitlint 配置模板：https://cz-git.qbb.sh/zh/config/

module.exports = {// 繼承的規則extends: ["@commitlint/config-conventional"],// 自定義規則rules: {// ......// cz-git 配置prompt: {messages: {type: "選擇你要提交的類型 :",scope: "選擇一個提交范圍（可選）:",customScope: "請輸入自定義的提交范圍 :",subject: "填寫簡短精煉的變更描述 :\n",body: "填寫更加詳細的變更描述（可選）。使用 "|" 換行 :\n",breaking: "列舉非兼容性重大的變更（可選）。使用 "|" 換行 :\n",footerPrefixesSelect: "選擇關聯issue前綴（可選）:",customFooterPrefix: "輸入自定義issue前綴 :",footer: "列舉關聯issue (可選) 例如: #31, #I3244 :\n",generatingByAI: "正在通過 AI 生成你的提交簡短描述...",generatedSelectByAI: "選擇一個 AI 生成的簡短描述:",confirmCommit: "是否提交或修改commit ?",},// prettier-ignoretypes: [{ value: "feat",     name: "特性:     ?  新增功能", emoji: ":sparkles:" },{ value: "fix",      name: "修復:     🐛  修復缺陷", emoji: ":bug:" },{ value: "docs",     name: "文檔:     📝  文檔變更", emoji: ":memo:" },{ value: "style",    name: "格式:     💄  代碼格式（不影響功能，例如空格、分號等格式修正）", emoji: ":lipstick:" },{ value: "refactor", name: "重構:     ??  代碼重構（不包括 bug 修復、功能新增）", emoji: ":recycle:" },{ value: "perf",     name: "性能:     ??  性能優化", emoji: ":zap:" },{ value: "test",     name: "測試:     ?  添加疏漏測試或已有測試改動", emoji: ":white_check_mark:"},{ value: "build",    name: "構建:     📦?  構建流程、外部依賴變更（如升級 npm 包、修改 vite 配置等）", emoji: ":package:"},{ value: "ci",       name: "集成:     🎡  修改 CI 配置、腳本",  emoji: ":ferris_wheel:"},{ value: "revert",   name: "回退:     ??  回滾 commit",emoji: ":rewind:"},{ value: "chore",    name: "其他:     🔨  對構建過程或輔助工具和庫的更改（不影響源文件、測試用例）", emoji: ":hammer:"},],useEmoji: true,emojiAlign: "center",useAI: false,aiNumber: 1,themeColorCode: "",scopes: [],allowCustomScopes: true,allowEmptyScopes: true,customScopesAlign: "bottom",customScopesAlias: "custom",emptyScopesAlias: "empty",upperCaseSubject: false,markBreakingChangeMode: false,allowBreakingChanges: ["feat", "fix"],breaklineNumber: 100,breaklineChar: "|",skipQuestions: [],issuePrefixes: [{ value: "closed", name: "closed:   ISSUES has been processed" }],customIssuePrefixAlign: "top",emptyIssuePrefixAlias: "skip",customIssuePrefixAlias: "custom",allowCustomIssuePrefix: true,allowEmptyIssuePrefix: true,confirmColorize: true,maxHeaderLength: Infinity,maxSubjectLength: Infinity,minSubjectLength: 0,scopeOverrides: undefined,defaultBody: "",defaultIssues: "",defaultScope: "",defaultSubject: "",},
};

添加 cz-git 腳本

在package.json 文件中添加 commit 腳本命令

 "scripts": {"commit": "git-cz"}

測試

先添加git add

執行 pnpm run commit 命令后，按照提示輸入相關信息，最終生成符合規范的提交信息。

請添加圖片描述

樣式處理

添加sass

👉 Sass是幫助開發者編寫、管理和維護樣式的強大工具，通過 <style lang="scss"> 使用。它提供變量、嵌套、混合等功能，提升了樣式的可維護性和開發效率，尤其在復雜項目中減少重復代碼、提高復用性。

pnpm add -D sass sass-loader

請添加圖片描述

四、功能實現

UnoCSS 原子化樣式

👉 UnoCSS 是一個高性能、靈活且按需生成的原子化 CSS 引擎。

官方網站：https://unocss.net/

先比較下

內部樣式

UnoCSS原子樣式

請添加圖片描述

安裝插件

👉 VSCode 安裝 UnoCSS 插件

請添加圖片描述

安裝依賴

本次整合基于官網提供的社區預設 unocss-preset-weapp。該預設內置了 transformer，用于解決小程序的兼容性問題。

請添加圖片描述

進一步參考 unocss-preset-weapp 的 uniapp_vue3 使用與配置指南，使用以下命令安裝 UnoCSS 和 unocss-preset-weapp：

pnpm add -D unocss unocss-preset-weapp

配置 UnoCSS

👉 參考 unocss-preset-weapp 的 uniapp_vue3 使用與配置指南，配置如下：

vite.config.ts

import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";export default defineConfig(async () => {const UnoCss = await import("unocss/vite").then(i => i.default);return {"plugins": [uni(),// 配置 UnoCSSUnoCss(),],};
});

unocss.config.ts

添加unocss.config.ts文件，搭配 unocss vscode 插件，智能提示

import { presetWeapp } from "unocss-preset-weapp";
import { extractorAttributify, transformerClass } from "unocss-preset-weapp/transformer";const { presetWeappAttributify, transformerAttributify } = extractorAttributify();export default {"presets": [// https://github.com/MellowCo/unocss-preset-weapppresetWeapp(),// attributify autocompletepresetWeappAttributify(),],"shortcuts": [{"flex-center": "flex justify-center items-center","flex-col": "flex flex-col",},],"transformers": [// https://github.com/MellowCo/unocss-preset-weapp/tree/main/src/transformer/transformerAttributifytransformerAttributify(),// https://github.com/MellowCo/unocss-preset-weapp/tree/main/src/transformer/transformerClasstransformerClass(),],
};

shortcuts 自定義樣式組合：可以在 shortcuts 中定義常用的樣式組合，以便簡化項目中的樣式使用和維護，避免冗余和重復的樣式。

main.ts
- ```
import 'uno.css'
```

測試

下圖展示了在 VSCode 中測試 UnoCSS 時，智能提示和樣式設置功能已經正常生效。

請添加圖片描述

此外，在 unocss.config.ts 文件中預設的 shortcuts 組合樣式也得到了正確應用。

請添加圖片描述

TabBar 導航

👉 在 APP 開發中，底部導航欄（TabBar）是移動端應用的重要部分，方便用戶在不同頁面間進行切換。

添加頁面

在初始化的模板項目中，src/pages 目錄下默認有一個 index/index.vue 頁面。為了更好地演示 TabBar 的切換效果，我們在 pages 目錄下再新增兩個頁面：

首頁（src/pages/home/index.vue）：

<template><view class="flex-center flex-col"><view><text class="text-cyan font-bold text-lg">工作臺</text></view></view>
</template>

我的（src/pages/profile/index.vue）：

<template><view class="flex-center flex-col"><view><text class="text-blue font-bold text-lg">我的</text></view></view>
</template>

添加圖標

在 src/static 目錄下創建一個 tabbar 文件夾，存放從 iconfont 獲取的圖標。每個圖標都需要有未激活和激活兩種狀態的樣式。

請添加圖片描述

配置 TabBar

在 UniApp 項目中，底部導航欄（TabBar）通過配置 pages.json 文件來實現。首先，找到并打開項目根目錄下的 src/pages.json 文件。在該文件中，可以為每個頁面配置導航欄，同時定義 TabBar。

下面是完整的配置示例，注意 tabBar 中的 pagePath 必須對應 pages 目錄下的實際頁面路徑。

{"pages": [//pages數組中第一項表示應用啟動頁，參考：https://uniapp.dcloud.io/collocation/pages{"path": "pages/index/index","style": {"navigationBarTitleText": "首頁"}},{"path": "pages/history/index","style": {"navigationBarTitleText": "歷史"}},{"path": "pages/profile/index","style": {"navigationBarTitleText": "我的"}}],"globalStyle": {"navigationBarTextStyle": "black","navigationBarTitleText": "uni-app","navigationBarBackgroundColor": "#F8F8F8","backgroundColor": "#F8F8F8"},"tabBar": {"color": "#8C8C8C","selectedColor": "#4080FF","backgroundColor": "#FFFFFF","borderStyle": "black","list": [{"pagePath": "pages/index/index","text": "首頁","iconPath": "static/tabbar/home.png","selectedIconPath": "static/tabbar/home-active.png"},{"pagePath": "pages/history/index","text": "歷史","iconPath": "static/tabbar/history.png","selectedIconPath": "static/tabbar/history-active.png"},{"pagePath": "pages/profile/index","text": "我的","iconPath": "static/tabbar/profile.png","selectedIconPath": "static/tabbar/profile-active.png"}]}
}

按需自動導入

👉 自動導入API和組件庫

在傳統的 Vue 開發中，我們通常需要在每個頁面手動導入 Vue 組合式 API（如 ref, reactive, onMounted 等）。隨著項目的增大，手動導入會增加代碼的冗余度，降低開發體驗。

通過對比，來看一下手動導入與按需自動導入的區別：

手動導入

按需自動導入

手動導入： 每個頁面都需要顯式地引入 ref, reactive, onMounted 等組合式 API。 按需自動導入： 配置了自動導入插件后，這些 API 無需顯式導入即可直接使用，減少了重復代碼，提高了開發效率。

由于當前還未整合按需自動導入插件，所以右圖的代碼仍然報錯，提示未找到 ref 和 reactive 的定義。這展示了按需自動導入的重要性：一旦整合插件，這類錯誤將被消除，代碼更加簡潔易維護。

安裝依賴

首先使用以下命令安裝 unplugin-auto-import 插件：

pnpm add -D unplugin-auto-import

配置自動導入

接著，在 vite.config.ts 中配置 unplugin-auto-import 插件，確保 Vue 和 UniApp 的 API 能夠自動按需導入。

// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import AutoImport from "unplugin-auto-import/vite";export default defineConfig(async () => {const UnoCss = await import("unocss/vite").then(i => i.default);return {"plugins": [uni(),// 配置 UnoCSSUnoCss(),AutoImport({"imports": ["vue", "uni-app"], // 自動導入 Vue 和 UniApp 的 API"dts": "src/types/auto-imports.d.ts", // 自動生成類型聲明文件"eslintrc": {"enabled": true, // 生成 ESLint 配置文件"filepath": "./.eslintrc-auto-import.json", // ESLint 配置文件路徑},}),],};
});

性能對比

配置 ESLint 規則

👉 ESLint 是一個可配置的 JavaScript/TypeScript 代碼檢查工具，用于發現并修復代碼中的錯誤、風格問題和潛在缺陷。

為了讓 ESLint 能識別這些通過 unplugin-auto-import 自動導入的 API，需要在 ESLint 的配置中引入 unplugin-auto-import 生成的 .eslintrc-auto-import.json 文件。

在 ESLint 9.x 版本中，使用 Flat Config 時不再支持 extends 關鍵字。因此，不能使用以下配置：

// 錯誤示例
export default [{extends: ["./.eslintrc-auto-import.json"], // 這種擴展方式在 Flat Config 中不再支持},
];

取而代之的是直接引入 .eslintrc-auto-import.json 文件內容，通過解析文件的方式將自動導入的全局變量配置整合進 ESLint 配置。

在 eslint.config.mjs 中添加如下配置：

// eslint.config.mjs 正確的配置
import { readFileSync } from "fs";
import { fileURLToPath } from "url";
import { dirname, resolve } from "path";// 動態讀取 .eslintrc-auto-import.json 文件內容
const autoImportConfig = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), ".eslintrc-auto-import.json"),"utf-8",),
);
export default [{// 語言選項配置，定義全局變量languageOptions: {globals: {// ......autoImportConfig.globals, // 自動導入的全局變量},},},
];

這樣配置后，ESLint 將能夠識別通過自動導入的 API，避免例如 'ref' is not defined 這樣的錯誤，從而使項目的開發更加順暢。

配置Prettier忽略規則

在.prettierignore 里添加忽略 eslint.config.mjs，避免自動引入文件每次都要格式化代碼

.prettierignore
node_modules
dist
public
*.min.js
auto-imports.d.ts

測試

通過上述步驟配置后，原先在未手動導入情況下報錯的頁面，現在可以正常使用 ref, reactive 等 API，而無需顯式導入。

以下是最終的效果：

請添加圖片描述

整合按需自動導入后，你將不再需要在每個頁面顯式導入 Vue 或 UniApp 的組合式 API，大幅度減少了重復的代碼，提升了開發體驗。

環境變量

👉 Vue3 的環境變量是通過 .env 文件動態管理不同環境（如開發、測試、生產）的配置參數（如接口地址、端口等），以 VITE_ 為前綴聲明，并通過 import.meta.env 在代碼中訪問，實現不同環境下的靈活切換

下面的整合過程參考 Vite 環境變量配置官方文檔

配置環境變量

項目根目錄新建 .env.development 、.env.production

開發環境變量配置：.env.development

# 變量必須以 VITE_ 為前綴才能暴露給外部讀取# 項目運行的端口號
VITE_APP_PORT = 5173# API 基礎路徑，開發環境下的請求前綴
VITE_APP_BASE_API = '/dev-api'# API 服務器的 URL
VITE_APP_API_URL = https://api.moxun.api

生產環境變量配置：.env.production

# API 基礎路徑，生產環境下的請求前綴
VITE_APP_BASE_API = '/prod-api'# API 服務器的 URL
VITE_APP_API_URL = https://api.moxun.api

智能提示

👉 在項目里提供提示

首先，在 src/types/env.d.ts 文件中添加環境變量的類型聲明：

// src/types/env.d.ts
interface ImportMetaEnv {/*** 應用端口*/VITE_APP_PORT: number;/*** API 基礎路徑*/VITE_APP_BASE_API: string;/*** API 服務器的 URL*/VITE_APP_API_URL: string;
}interface ImportMeta {readonly env: ImportMetaEnv;
}

確保 TypeScript 編譯器使用的模塊系統支持 import.meta。在 tsconfig.json 文件中，你可以指定 es2020、es2022 或 esnext 等模塊系統。例如：

// tsconfig.json
{"compilerOptions": {"module": "esnext",  // 支持 import.meta// ...}
}

在任意頁面中測試 import.meta 是否能夠智能提示環境變量：

請添加圖片描述

HTTP請求封裝

👉 HTTP 請求封裝通過統一管理接口配置、自動攜帶 Token、集中處理錯誤與緩存優化，減少重復代碼，提升開發效率和代碼維護性，并實現跨平臺兼容性（如 H5 端適配）

通過一個登錄案例演示如何在Uniapp中整合HTTP請求。這里未使用axios和alova請求庫的原因在于，Uniapp自身提供了跨平臺的uni.request方法，該方法在不同平臺（如小程序、App和H5）下表現一致，且無需額外安裝第三方庫，從而減少了項目的依賴復雜性和體積。

封裝請求工具

在 global.d.ts 中定義全局響應數據類型 ResponseData：

// src/types/global.d.ts
declare global {/*** 響應數據結構*/interface ResponseData<T = any> {code: string;  // 業務狀態碼data: T;       // 返回數據msg: string;   // 消息}
}
export {};

在 src/utils/request.ts 下創建一個 HTTP 請求工具，用于與 API 服務器進行通信：

// src/utils/request.ts
export default function request<T>(options: UniApp.RequestOptions): Promise<T> {const token = uni.getStorageSync("token"); // 從本地緩存獲取 token
?return new Promise((resolve, reject) => {uni.request({...options,// VITE_APP_API_URL 是在 Vite 項目的 .env.development 文件中配置的環境變量，表示 API 的路徑"url": `${import.meta.env.VITE_APP_API_URL}${options.url}`,"header": {...options.header,"Authorization": token,},"success": (response) => {const resData = response.data as ResponseData<T>;// 業務狀態碼 00000 表示成功if (resData.code === "00000") {resolve(resData.data);} else {uni.showToast({"title": resData.msg || "業務處理失敗","icon": "none","duration": 2000,});reject({"message": resData.msg || "業務處理失敗","code": resData.code,});}},"fail": (error) => {uni.showToast({"title": "網絡請求失敗","icon": "none","duration": 2000,});reject({"message": "網絡請求失敗",error,});},});});
}

注意事項

當首次使用該請求工具類時，可能會出現 'uni' is not defined 的 ESLint 錯誤，如下圖所示：

請添加圖片描述

為解決此問題，需要在 ESLint 配置文件中定義 uni 為全局變量：

// eslint.config.mjs
export default [{// 語言選項配置，定義全局變量languageOptions: {globals: {// ......{uni: "readonly", // uni-app 全局對象},},},},
];

登錄接口定義

請求URL: https://api.moxun.cn/api/v1/auth/login

請求參數：

表格還在加載中，請等待加載完成后再嘗試復制

返回響應：

{"code": "200","data": {"accessToken": "RyJ0eXDiOiJKV1WiLCJhbGcrOiJIUzI1NiJ9.eKJzdSIxxx.xxxxxxx","tokenType": "Bearer"},"msg": "ok"
}

根據上述登錄接口信息，創建 AuthAPI 類用于處理登錄請求：

import request from "@/utils/request";const AuthAPI = {/*** 登錄接口** @param username 用戶名* @param password 密碼* @returns 返回 token*/login(username: string, password: string): Promise<LoginResult> {return request<LoginResult>({url: "/api/v1/auth/login",method: "POST",data: {username,password,},header: {"Content-Type": "application/x-www-form-urlencoded",},});},/*** 登出接口*/logout(): Promise<void> {return request({url: "/api/v1/auth/logout",method: "DELETE",});},
};export default AuthAPI;/** 登錄響應 */
export interface LoginResult {/** 訪問token */accessToken?: string;/** token 類型 */tokenType?: string;
}

登錄頁面

新建 src/pages/login/index.vue 文件，編寫登錄頁面及邏輯：

<template><view class="flex-col"><input v-model="username" placeholder="請輸入用戶名" /><input v-model="password" placeholder="請輸入密碼" type="password" /><button @click="handleLogin">登錄</button></view>
</template><script lang="ts" setup>
import AuthAPI, { LoginResult } from "@/api/auth";const username = ref("");
const password = ref("");const handleLogin = async () => {try {const response: LoginResult = await AuthAPI.login(username.value, password.value);if (response.accessToken) {uni.setStorageSync("token", response.accessToken);uni.showToast({ "title": "登錄成功", "icon": "success" });} else {uni.showToast({ "title": "登錄失敗", "icon": "none" });}} catch (err) {uni.showToast({ "title": "登錄失敗", "icon": "none" });}
};
</script><style scoped>
</style>

在 pages.json 文件中，聲明登錄頁面的路由：

// src/pages.json
{"pages": [{"path": "pages/login/index","style": {"navigationBarTitleText": "登錄"}}]
}

登錄測試

訪問登錄頁面：http://localhost:5173/#/pages/login/index，輸入用戶名和密碼 (admin/123456) 測試登錄接口，登錄成功后可以看到返回的訪問令牌。

Pinia 狀態管理

👉 Pinia 是 Vue 的狀態管理庫，專為跨組件或頁面共享狀態設計。

Pinia 官方文檔:

https://pinia.vuejs.org/zh/getting-started.html

安裝依賴

首先，安裝 pinia 依賴：

pnpm add pinia

全局注冊

在項目的 src 目錄下創建 store 文件夾，并新建 index.ts 文件，初始化并注冊 Pinia 實例。

// src/store/index.ts
import type { App } from "vue";
import { createPinia } from "pinia";
?
const store = createPinia();
// 注冊 Pinia
export function setupStore(app: App<Element>) {app.use(store); // 全局注冊 Pinia
}

接著，將 store 在項目入口文件 main.ts 中引入，并將其作為全局插件傳遞給應用：

// src/main.ts
import { createSSRApp } from "vue";
import App from "./App.vue";import { setupStore } from "@/store";export function createApp() {const app = createSSRApp(App);// 全局注冊 storesetupStore(app);return {app,};
}

接下來，我們通過 Pinia 管理登錄狀態和用戶信息，并在多個頁面共享狀態。

用戶信息接口

編寫一個 API 來獲取當前登錄用戶的信息：

import request from "@/utils/request";const USER_BASE_URL = "/api/v1/users";const UserAPI = {/*** 獲取當前登錄用戶信息** @returns 登錄用戶昵稱、頭像信息，包括角色和權限*/getUserInfo(): Promise<UserInfo> {return request<UserInfo>({url: `${USER_BASE_URL}/me`,method: "GET",});},
};
export default UserAPI;
?
/** 登錄用戶信息 */
export interface UserInfo {/** 用戶ID */userId?: number;
?/** 用戶名 */username?: string;
?/** 昵稱 */nickname?: string;
?/** 頭像URL */avatar?: string;
?/** 角色 */roles: string[];
?/** 權限 */perms: string[];
}

用戶狀態管理

通過 Pinia 定義 user 模塊，管理登錄狀態、用戶信息等。

//  src/store/module/user.ts
import { defineStore } from "pinia";
import AuthAPI from "@/api/auth";
import UserAPI, { UserInfo } from "@/api/user";
?
export const useUserStore = defineStore("user", () => {// 確保 token 是響應式的const token = ref<string>(uni.getStorageSync("token") || "");const userInfo = ref<UserInfo | null>(null);
?// 登錄const login = async (username: string, password: string) => {const { tokenType, accessToken } = await AuthAPI.login(username, password);token.value = `${tokenType} ${accessToken}`; // Bearer tokenuni.setStorageSync("token", token.value);};
?// 獲取用戶信息const getUserInfo = async () => {const info = await UserAPI.getUserInfo();userInfo.value = info;};
?// 登出const logout = async () => {await AuthAPI.logout();userInfo.value = null;token.value = ""; // 清空 tokenuni.removeStorageSync("token"); // 從本地緩存移除 token};
?return {token,userInfo,login,logout,getUserInfo,};
});

個人中心頁面

個人中心頁面展示用戶的頭像和昵稱，未登錄時引導用戶去登錄。

<template><view class="flex-center flex-col"><text class="text-blue font-bold text-lg">我的</text>
?<!-- 判斷是否已登錄 --><template v-if="isLoggedIn"><image :src="userInfo?.avatar" class="w100 h100 mb-5 rounded-full" /><text class="text-lg font-bold">{{ userInfo?.nickname }}</text><button @click="handleLogout" class="mt-5">退出登錄</button></template>
?<!-- 未登錄時顯示去登錄按鈕 --><template v-else><text>您還未登錄，請先登錄</text><button @click="goToLoginPage" class="mt-5">去登錄</button></template></view>
</template>
?
<script lang="ts" setup>
import { useUserStore } from "@/store/modules/user";
?
// 使用 pinia
const userStore = useUserStore();
?
const isLoggedIn = computed(() => userStore.token);
const userInfo = computed(() => userStore.userInfo);
?
// 跳轉到登錄頁面
const goToLoginPage = () => {uni.navigateTo({ url: "/pages/login/index" });
};
?
// 退出登錄處理
const handleLogout = async () => {await userStore.logout();uni.showToast({ title: "已退出登錄", icon: "success" });
};
</script>

登錄頁通過 Pinia 實現用戶信息的全局狀態管理，并在登錄成功后跳轉到個人中心頁面。

源碼版本

https://gitee.com/moxunjinmu/uniapp-vue3-template/tree/dev%2FPinia/

反向代理

👉 反向代理是通過配置開發服務器（如vue.config.js中的devServer.proxy），將前端請求轉發至目標后端服務器，解決跨域問題并簡化API調用，例如將/api路徑請求代理到真實后端地址，實現開發環境下的無縫通信

在開發中，若服務端沒有啟用 CORS（跨域資源共享），瀏覽器會基于安全策略攔截跨域請求，導致無法訪問接口。為了繞過這個問題，我們可以通過 Vite 的反向代理功能，將開發階段的請求代理到真實的 API 服務器上，偽裝成同源請求。

環境變量配置

之前我們已經配置了環境變量，以下是 .env.development 中的相關配置：

# 變量必須以 VITE_ 為前綴才能暴露給外部讀取
?
# 項目運行的端口號
VITE_APP_PORT = 5173
?
# API 基礎路徑，開發環境下的請求前綴
VITE_APP_BASE_API = '/dev-api'
?
# API 服務器的 URL
VITE_APP_API_URL = https://api.moxun.cn

請求工具的調整

為了讓請求走代理，我們需要在請求工具中將 VITE_APP_API_URL 替換為 VITE_APP_BASE_API。這樣，所有對 API 的請求都會通過代理標識 /dev-api 進行轉發。

export default function request<T>(options: UniApp.RequestOptions): Promise<T> {return new Promise((resolve, reject) => {uni.request({...options,// 原請求方式: 使用真實 API URL// url: `${import.meta.env.VITE_APP_API_URL}${options.url}`, // 示例: https://api.moxun.cn/login// VITE_APP_BASE_API 是在 Vite 項目的 .env.development 文件中配置的環境變量，使用代理標識，實際轉發到真實 APIurl: `${import.meta.env.VITE_APP_BASE_API}${options.url}`, // 示例: http://localhost:5173/dev-api/login});});
}

Vite 反向代理配置

接下來，在 vite.config.ts 中添加反向代理配置，將 /dev-api 的請求代理到 VITE_APP_API_URL，通過 http-proxy 實現請求的轉發。

// vite.config.ts
import { defineConfig, UserConfig, ConfigEnv, loadEnv } from "vite";
?
export default defineConfig(async ({ mode }: ConfigEnv): Promise<UserConfig> => {const env = loadEnv(mode, process.cwd());
?return {server: {host: "0.0.0.0",port: +env.VITE_APP_PORT,open: true,// 反向代理配置proxy: {[env.VITE_APP_BASE_API]: {target: env.VITE_APP_API_URL, // 目標服務器changeOrigin: true,           // 支持跨域rewrite: (path) => path.replace(new RegExp("^" + env.VITE_APP_BASE_API), ""), // 去掉前綴},},},plugins: [// 插件配置...],};
});

測試與驗證

在配置好反向代理后，瀏覽器發出的請求將被 Vite 的代理服務器攔截并轉發至真實的 API 地址。例如，瀏覽器請求 http://localhost:5173/dev-api/api/v1/auth/login 時，Vite 會將該請求代理到 https://api.moxun.cn/api/v1/auth/login。

瀏覽器認為請求的 URL 與應用的主機地址一致，因此不會阻止該請求，即便真實請求已通過代理轉發到外部服務器。

需要注意，反向代理的目標是偽裝請求來源，雖然它繞過了瀏覽器的同源策略，但有時也會讓開發者誤以為請求地址錯誤。實際上，這是由于代理轉發過程造成的表面請求地址與真實請求地址的差異。

源碼地址

https://gitee.com/moxunjinmu/uniapp-vue3-template/tree/dev%2Fdev1.0/

五、UI 框架集成

uView-plus（適配Vue3的版本）

官網地址：https://uiadmin.net/uview-plus/components/intro.html

👉 uview-plus是uni-app生態專用的UI框架，uni-app 是一個使用 Vue.js 開發所有前端應用的框架，開發者編寫一套代碼，可發布到iOS、Android、H5、以及各種小程序(微信/支付寶/百度/頭條/QQ/釘釘)等多個平臺(引言自uni-app網)。但目前除微信小程序，其它小程序平臺的兼容可能存在一些問題，后續會針對這方面持續優化。

安裝uView-plus核心庫

pnpm add uview-plus  # 或npm/yarn

配置main.ts

在src/main.ts中引入并掛載uView：

import { createSSRApp } from 'vue'
import App from './App.vue'
import uViewPlus from 'uview-plus'
?
export function createApp() {const app = createSSRApp(App)app.use(uViewPlus)return { app }
}

類型聲明配置（TypeScript項目）

修改src/env.d.ts，添加類型聲明：

/// <reference types="vite/client" />
declare module 'uview-plus'

樣式文件引入

全局SCSS變量（uni.scss）

在項目根目錄的uni.scss中添加：

@import 'uview-plus/theme.scss';

基礎樣式（App.vue）

在App.vue的<style>中引入：

<style lang="scss">
@import "uview-plus/index.scss";
</style>

自動導入組件配置

配置easycom規則

在pages.json中添加：

{"easycom": {"autoscan": true,"custom": {"^u-(.*)": "uview-plus/components/u-$1/u-$1.vue","^up-(.*)": "uview-plus/components/u-$1/u-$1.vue"}}
}

驗證安裝

測試組件

在頁面中使用uView組件，例如：

<template><view><u-button type="primary">測試按鈕</u-button></view>
</template>

重啟項目

運行pnpm dev:mp-weixin（或其他平臺命令），查看組件是否正常渲染。

Sass報警@import

在sass1.8.0以上版本報錯Deprecation Warning: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0. 因為新版本Sass的@use語法較為激進，如果升級為@use將會是破壞式更新，所以推薦將sass固定在以下版本結局報警。

"sass": "1.63.2",
"sass-loader": "10.4.1",

源碼

整合uview-plus 代碼版本: https://gitee.com/moxunjinmu/uniapp-vue3-template/tree/dev%2Fdev2.0-uviewPlus/

`wot-design-uni`

👉 wot-design-uni 是基于 Vue 3 和 TypeScript 構建的高質量組件庫。組件庫遵循 Wot Design 的設計規范，提供 70 多個組件，支持暗黑模式、國際化和自定義主題，旨在為開發者提供一致的 UI 交互，同時提高開發效率。

說明： 本文檔整合步驟基于 wot-design-uni 官方文檔編寫，建議開發者參考官方文檔進行安裝和配置，以確保組件庫的正確使用。

安裝依賴

使用 pnpm 安裝組件庫的依賴：

pnpm add wot-design-uni

配置自動引入組件

在 pages.json 文件中配置 easycom 自動引入：

// pages.json
{"easycom": {"autoscan": true,"custom": {"^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"}},"pages": [// 這里是項目已有的內容]
}

關于 easycom* ：* easycom 是 uni-app 提供的自動化引入功能，更多細節請參考 easycom 官方文檔。

Volar 支持

為了讓 Volar 正確識別和提示全局組件，你需要在項目的 tsconfig.json 文件中配置全局組件類型支持：

// tsconfig.json
{"compilerOptions": {"types": ["wot-design-uni/global"]}
}

這將確保你在 TypeScript 項目中編寫代碼時，Volar 能提供完整的類型支持和代碼提示。

測試組件

安裝和配置完成后，你可以開始使用 wot-design-uni 的組件。在頁面中，直接寫組件標簽即可，無需手動導入和注冊：

<template><view><wd-button size="small">主要按鈕</wd-button><wd-button type="success" size="small">成功按鈕</wd-button><wd-button type="info" size="small">信息按鈕</wd-button><wd-button type="warning" size="small">警告按鈕</wd-button><wd-button type="error" size="small">危險按鈕</wd-button></view>
</template>

你將看到如下按鈕效果：

請添加圖片描述

Sass報警@import

"sass": "1.63.2",
"sass-loader": "10.4.1",

源碼

整合wot-design-uni 代碼版本: https://gitee.com/moxunjinmu/uniapp-vue3-template/tree/dev%2Fdev2.0-Wot/

六、項目部署

H5 部署

👉 執行 pnpm run build:h5 命令來完成項目的打包：

pnpm run build:h5

打包后生成的靜態文件位于 dist/build/h5 目錄下。將該目錄下的文件復制到服務器的 /usr/share/nginx/html/``uniapp-vue3-template 目錄。

接下來，配置 nginx：

# nginx.conf
server {listen 80;server_name localhost;location / {root /usr/share/nginx/html/uniapp-vue3-template;index index.html index.htm;}# 反向代理配置location /prod-api/ {# 將 api.moxun.cn替換為后端 API 地址，注意保留后面的斜杠 /proxy_pass http://api.moxun.cn/; }
}

這樣配置完成后，就可以通過 nginx服務器來訪問你的項目了。

小程序發布

👉 微信小程序是微信生態內無需下載安裝的輕量級應用，支持即用即走、跨平臺運行（iOS/Android），提供原生體驗及微信核心功能（支付、分享等），降低開發成本并提升用戶觸達效率。

下載工具

下載 HBuilder X 編輯器

下載微信開發者工具

獲取小程序 AppID

訪問微信公眾平臺申請小程序，獲取 AppID。如果已申請，可在 首頁 → 小程序信息 → 查看詳情 查看 AppID

請添加圖片描述

配置項目

使用 HBuilder X 打開項目，修改 manifest.json 文件中的小程序配置，并填寫獲取的 AppID。

請添加圖片描述

設置微信開發者工具

使用微信掃碼登錄微信開發者工具，開啟服務端口：點擊工具欄設置→安全設置→安全→服務端口，選擇打開。

請添加圖片描述

運行項目

在 HBuilder X 中，點擊 運行→運行到小程序模擬器→微信開發者工具。

請添加圖片描述

項目編譯完成后，微信開發者工具會自動啟動并呈現頁面。

請添加圖片描述

上傳發布

在微信開發者工具中，點擊 上傳 將應用發布到小程序平臺。
請添加圖片描述

查看效果

最后，使用手機打開小程序查看效果.

結語

通過本文的系統講解，我們完整呈現了如何從零構建一個基于 Vue3 + TypeScript 的 UniApp 跨端開發腳手架。整個流程涵蓋了：

基礎環境搭建 - 從 Node.js 環境配置到 Vue CLI 安裝
項目初始化 - 創建支持 Vite 和 TypeScript 的 uni-app 項目模板
代碼規范體系 - 集成 ESLint + Prettier + Stylelint 的完整前端規范解決方案
工程化配置 - 通過 Husky + lint-staged + Commitizen 實現 Git 提交規范化
核心功能集成 - 包括：
1. UnoCSS 原子化樣式方案
2. Pinia 狀態管理
3. 自動按需導入
4. HTTP 請求封裝
5. 環境變量管理
組件庫整合 - 接入 wot-design-uni 組件庫
多端部署 - 詳細說明 H5 和小程序的發布流程