mmsUnix 安装与配置教程

uni_modules/m-unix · easycom · main.uts（app.use(mUnix)）· App.uvue 全局样式 — 分步与 Gitee 示例工程对齐，可按项目删减

简述

把 m-unix 放入 uni_modules，配置 easycom、在 main.uts 中 app.use(mUnix)，并在 App.uvue 引入 index.scss，即可使用 m-* 组件。安装步骤与 Gitee · mms-unix 示例工程一致，可按自身项目删掉不需要的部分（如无 common/config 可去掉注入；无多语言可去掉 initI18n）。

TIP

组件 API 与演示索引：见 components-catalog.md。全局样式与图标字体均在 App.uvue（见下文 第 5 步）；名称映射、自建 iconfont 见 m-icon。

获取方式

DCloud 插件市场：mmsUnix · uni-app-x 基础组件库 — 建议 HBuilderX 3.1.0+。
源码仓库：Gitee · mms-unix — 使用其中的 uni_modules/m-unix。

完整约定以 uni_modules/m-unix/readme.md 为准。

安装教程

1. 环境要求

HBuilderX（支持 uni-app x 的版本）
uni-app x 工程
Node.js（按你工程与 HBuilderX 要求）

2. 放置 `m-unix`

text

your-project/
└── uni_modules/
    └── m-unix/

3. `pages.json`：easycom

与示例仓库一致：

json

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^m-(.*)": "@/uni_modules/m-unix/components/m-$1/m-$1.uvue"
    }
  }
}

4. `main.uts`：注入（可选）+ `mUnix` + `createApp`

顺序很重要：若使用宿主 common/config，须在 第一行先执行注入，再 import mUnix。

示例（与 mms-unix 仓库一致；可按需删减）：

typescript

import './inject-m-unix-host.uts'
// 若无 common/config，请删除上一行，并移除 inject-m-unix-host.uts 文件
import App from './App.uvue'
import { createSSRApp } from 'vue'
import mUnix from '@/uni_modules/m-unix'
import { initI18n } from '@/uni_modules/m-unix/locale/index.uts'

export function createApp() {
  initI18n()
  // 若工程无 @/locale/zh-Hans.json 等，请去掉 initI18n 及对 locale 的 import

  const app = createSSRApp(App)
  app.use(mUnix)
  return { app }
}

inject-m-unix-host.uts 内容应为：从 @/common/config 读出配置，调用 injectMUnixHostProjectConfig(config)。不使用业务注入时不要引用该文件。
initI18n()：依赖包内 locale/index.uts 对 @/locale/zh-Hans.json 等路径的引用；新建宿主无多语言资源时可整体去掉。

5. `App.uvue`：全局样式 + 图标字体

mms-unix 把 index.scss 与 loadFontFace 都放在 App.uvue（样式块 + onLaunch），与示例仓库一致。

（1）全局样式

在 App.uvue 根级样式中引入（也可改在 uni.scss，只要全局能吃到即可）：

vue

<style lang="scss">
@import '@/uni_modules/m-unix/index.scss';
</style>

（2）图标字库文件（`m-icon` 等必做）

m-icon 依赖 font-family: iconfont。将 iconfont.ttf 放到：

text

your-project/
└── static/
    └── iconfont/
        └── iconfont.ttf

路径与样式一致（一般为 /static/iconfont/iconfont.ttf）。字库须与 m-icon 内 getIconChar 映射一致；自建 iconfont 见 m-icon。

index.scss 已含 .iconfont 等基础样式；除非自建字族与 @font-face，一般不必再抄一套 .iconfont {}。

（3）非小程序：`uni.loadFontFace`

小程序通常依赖包内 libs/css/mp.scss 的 @font-face，一般不必在 App.uvue 再调 loadFontFace。
App / H5 在 onLaunch 中配合 #ifndef MP：

vue

<script setup>
	onLaunch(() => {
		// #ifndef MP
		uni.loadFontFace({
			family: 'iconfont',
			source: 'url("/static/iconfont/iconfont.ttf")',
			success: () => {
				console.log('图标字体加载成功')
			},
			fail: (err) => {
				console.log('图标字体加载失败', err)
			}
		})
		// #endif
	})
</script>

也可抽成 loadIconFont() 再在 onLaunch 里调用（与 mms-unix 仓库相同）。

（4）验证与延伸阅读

运行后打开含 m-icon 的页面，确认显示为字形而非方块。更多见 m-icon 与 uni_modules/m-unix/readme.md「图标字体」。

`App.uvue`：示例工程里多出来的逻辑

mms-unix 示例在 onLaunch 里还会调 checkForUpdate()（微信小程序 getUpdateManager）；Android / 鸿蒙 App 上另有「再按一次退出」。你若不需要，可直接删掉下列代码。Ut.uts 里 jumpTo 写死了示例 Tab 路径，业务工程 Tab 不同请勿照抄，应自写跳转或改工具。

摘自示例 App.uvue（不含第 5 步已介绍的 loadIconFont / 样式，仅作参照）：

vue

<script setup>
	onLaunch(() => {
		console.log('App Launch')
		checkForUpdate()
	})

	function checkForUpdate() {
		const uniAny = uni as any
		if (typeof uniAny.canIUse === 'function' && uniAny.canIUse('getUpdateManager')) {
			const updateManager = uniAny.getUpdateManager()
			updateManager.onCheckForUpdate((res) => {
				console.log('检查更新结果：', res.hasUpdate)
			})
			updateManager.onUpdateReady(() => {
				uni.showModal({
					title: '更新提示',
					content: '新版本已经准备好，是否重启应用？',
					success: (modalRes) => {
						if (modalRes.confirm) {
							updateManager.applyUpdate()
						}
					},
				})
			})
			updateManager.onUpdateFailed(() => {
				uni.showModal({
					title: '更新提示',
					content: '新版本下载失败，请检查网络后重试',
					showCancel: false,
				})
			})
		}
	}

	onShow(() => {
		console.log('App Show')
	})

	onHide(() => {
		console.log('App Hide')
	})

	// #ifdef APP-ANDROID || APP-HARMONY
	let firstBackTime = 0
	onLastPageBackPress(() => {
		console.log('App LastPageBackPress')
		if (firstBackTime == 0) {
			uni.showToast({
				title: '再按一次退出应用',
				position: 'bottom',
			})
			firstBackTime = Date.now()
			setTimeout(() => {
				firstBackTime = 0
			}, 2000)
		} else if (Date.now() - firstBackTime < 2000) {
			firstBackTime = Date.now()
			uni.exit()
		}
	})

	onExit(() => {
		console.log('App Exit')
	})
	// #endif
</script>

业务注入：`common/config` 与 `ProjectConfig`

使用 http / m-login / m-upload / m-update 等读取 getHostProjectConfig() 的能力前：

在宿主建立 common/config（结构与包内 readme.md「业务配置」一致）。
main.uts 最先 import './inject-m-unix-host.uts'，其中调用 injectMUnixHostProjectConfig(config)。
未注入时库内有安全默认值，工程可编译；真实联调需补齐 baseUrl、api 等。

详情见 uni_modules/m-unix/readme.md 与 components/m-tools/ProjectConfig.uts。

`$m` 能怎么用（不要再写 `uni.$m`）

执行 app.use(mUnix) 后，工具会挂到 Vue.config.globalProperties.$m：

选项式：this.$m
模板：$m
非组件的 .uts 脚本：请 import 对应模块（如 Request.uts、Storage.uts），不要假设存在 uni.$m（包内 mount$m 已废弃）。

使用组件与工具（示例）

在已配置 easycom 的前提下：

template

<m-button type="primary">确定</m-button>
<m-icon name="arrow-right"></m-icon>

组合式登录态（推荐直接 import）：

uts

import { useAuth } from '@/uni_modules/m-unix/components/m-tools/useAuth.uts'

m-update 需传入宿主 check-update-fn（签名与业务 checkUpdate 一致），否则不会真正请求版本接口；示例见 readme.md。

`common/config` 示例（结构参考）

以下为字段结构参考，具体字段以 readme.md 与 ProjectConfig.uts 为准：

typescript

export const config = {
  baseUrl: 'https://api.example.com',
  storage: { token: 'token', userInfo: 'userInfo' },
  loginRequiredPaths: [] as string[],
  loginPagePath: '/pages/login/login',
  api: {
    login: { /* ... */ },
    update: { checkUpdate: '/api/v1/common/checkUpdate' },
  },
  configInfo: {
    name: '你的应用',
    logo: '',
    desc: '',
    versionCode: 1,
    versionName: '1.0.0',
    userAgreementArticleId: '',
    privacyPolicyArticleId: '',
  },
}

常用组件列表

组件名	说明
m-button	按钮
m-icon	图标（见字体接入）
m-card	卡片
m-cell	单元格
m-dialog	弹窗
m-toast	提示框
m-loading	加载动画
m-popup	弹出层
m-search	搜索框
m-grid	宫格布局
m-row / m-col	栅格布局
m-login	登录
m-wx-login	微信一键登录
m-qrcode	二维码
m-upload	文件上传
m-watermark	水印
m-update	版本更新检测

常用 `$m` 能力（节选）

详见 Ut.uts / libs/utils.uts 合并结果；以下为常见入口：

名称	说明
`$m.storage` / 包内 `storage`	与 `Storage.uts` 一致
`$m.http` / `$m.request`	与 `Request.uts` 一致
`$m.jumpTo`	跳转（注意 Tab 路径是否与你的工程一致）
`$m.checkPhone`、`$m.isEmpty` 等	工具方法
`$m.msg`、`$m.toast` 等	以 `Ut.uts` 导出为准

useAuth：建议在 <script setup> 中 import，勿依赖过时的 uni.$m 叙述。

项目结构（节选）

text

uni_modules/m-unix/
├── components/
│   ├── m-tools/
│   │   ├── ProjectConfig.uts   # injectMUnixHostProjectConfig / getHostProjectConfig
│   │   ├── Request.uts
│   │   ├── Storage.uts
│   │   ├── useAuth.uts
│   │   └── ...
│   ├── m-button/
│   └── ...
├── locale/index.uts              # initI18n（依赖宿主 @/locale）
├── index.scss
└── index.js                      # app.use 安装入口

注意事项

本组件库面向 uni-app x，请以 .uvue + UTS 与 官方文档 为准。
easycom + app.use(mUnix) 是组件与 $m 的常规接入方式。
不要再使用文档旧版本中 uni.$m、configure()、addInterceptor() 等非本包导出 API 的写法；以 index.js 导出与 readme.md 为准。

简述 ​

获取方式 ​

安装教程 ​

1. 环境要求 ​

2. 放置 m-unix ​

3. pages.json：easycom ​

4. main.uts：注入（可选）+ mUnix + createApp ​

5. App.uvue：全局样式 + 图标字体 ​

（1）全局样式 ​

（2）图标字库文件（m-icon 等必做） ​

（3）非小程序：uni.loadFontFace ​

（4）验证与延伸阅读 ​

App.uvue：示例工程里多出来的逻辑 ​

业务注入：common/config 与 ProjectConfig ​

$m 能怎么用（不要再写 uni.$m） ​

使用组件与工具（示例） ​

common/config 示例（结构参考） ​

常用组件列表 ​

常用 $m 能力（节选） ​

项目结构（节选） ​

简述

获取方式

安装教程

1. 环境要求

2. 放置 `m-unix`

3. `pages.json`：easycom

4. `main.uts`：注入（可选）+ `mUnix` + `createApp`

5. `App.uvue`：全局样式 + 图标字体

（1）全局样式

（2）图标字库文件（`m-icon` 等必做）

（3）非小程序：`uni.loadFontFace`

（4）验证与延伸阅读

`App.uvue`：示例工程里多出来的逻辑

业务注入：`common/config` 与 `ProjectConfig`

`$m` 能怎么用（不要再写 `uni.$m`）

使用组件与工具（示例）

`common/config` 示例（结构参考）

常用组件列表

常用 `$m` 能力（节选）

项目结构（节选）