❌

阅读视图

发现新文章，点击刷新页面。

Unibest：新一代uni-app工程化最佳实践指南

✇掘金 前端
宇余

在uni-app生态日益成熟的今天，开发者对工程化、性能优化和跨端一致性的需求愈发迫切。Unibest作为一套基于uni-app的企业级工程化方案，整合了路由封装、状态管理、请求拦截、组件规范等核心能力，旨在降低大型项目开发成本，提升团队协作效率。本文将从核心特性、快速上手、实战技巧三个维度，带你全面掌握Unibest的使用方法。

一、Unibest核心特性解析

Unibest并非简单的模板集合，而是经过多个生产项目验证的工程化体系，其核心特性可概括为以下四点：

1.1 开箱即用的工程化方案

Unibest内置了完整的工程化配置，无需开发者手动搭建：

  • 路由管理：基于uni-simple-router封装，支持路由守卫、动态路由和路由别名，解决原生uni-app路由跳转繁琐的问题。

  • 请求层封装：统一的request拦截器，支持请求头添加、错误统一处理、loading自动控制，同时兼容mock数据和生产环境切换。

  • 代码规范：集成ESLint + Prettier + Husky，强制代码风格统一，减少团队协作冲突。

1.2 跨端一致性保障

针对uni-app跨端开发中常见的样式差异、API兼容性问题，Unibest提供了针对性解决方案：

  • 样式解决方案：内置px2rpx自动转换，配合scss变量和mixin，确保多端样式一致性；提供适配H5、小程序、App的样式隔离方案。

  • API适配层：对uni-app原生API进行二次封装，处理不同平台的差异逻辑，如支付、分享等功能的跨端兼容。

1.3 性能优化内置

Unibest从初始化阶段就融入了性能优化理念：

核心优化点：页面懒加载、图片懒加载、分包加载配置、大型组件异步引入，启动速度较原生uni-app提升30%+（基于官方测试数据）。

1.4 丰富的生态集成

无缝对接uni-app生态的同时，扩展了常用工具库：

  • 状态管理：支持Pinia/Vuex，提供模块化状态管理模板；

  • UI组件：兼容uView、ColorUI等主流UI库，同时提供自定义业务组件模板；

  • 工具函数：集成日期处理、加密解密、数据格式化等常用工具。

二、Unibest快速上手教程

只需三步，即可搭建基于Unibest的项目：

2.1 环境准备

确保已安装以下依赖：



# 安装Node.js（v14+）
# 安装uni-app CLI
npm install -g @dcloudio/cli
# 安装pnpm（推荐）
npm install -g pnpm

2.2 创建项目

使用Unibest模板创建新项目：



# 克隆Unibest模板
git clone https://github.com/unibest-team/unibest.git my-unibest-project
# 进入项目目录
cd my-unibest-project
# 安装依赖
pnpm install

2.3 运行项目

支持多端运行命令：



# 运行到微信小程序
pnpm dev:mp-weixin
# 运行到H5
pnpm dev:h5
# 运行到App（需配合HBuilderX）
pnpm dev:app-plus

2.4 目录结构解析

Unibest采用约定式目录结构，核心目录说明：

目录 功能说明
/src/api 接口请求封装
/src/router 路由配置和守卫
/src/store Pinia/Vuex状态管理
/src/components 公共组件和业务组件
/src/utils 工具函数集合

三、Unibest实战技巧

3.1 多环境配置

在/src/env目录下配置不同环境的接口地址：



// .env.development
VITE_BASE_URL = 'https://dev-api.unibest.com'

// .env.production
VITE_BASE_URL = 'https://api.unibest.com'

通过命令自动切换环境：



# 开发环境
pnpm dev:mp-weixin --mode development
# 生产环境
pnpm build:mp-weixin --mode production

3.2 组件封装最佳实践

以自定义按钮组件为例，Unibest推荐的封装方式：



<template>
  <button 
    class="u-btn" 
    :class="{ 'u-btn--primary': type === 'primary' }"
    @click="handleClick"
  >
    <slot></slot>
  </button>
</template>

<script setup>
const props = defineProps({
  type: {
    type: String,
    default: 'default'
  }
})

const emit = defineEmits(['click'])

const handleClick = (e) => {
  emit('click', e)
}
</script>

<style scoped lang="scss">
.u-btn {
  padding: 12rpx 24rpx;
  border-radius: 8rpx;
  &--primary {
    background: #007aff;
    color: #fff;
  }
}
</style>

3.3 路由守卫应用

在/src/router/guard.js中配置全局路由守卫：



// 登录拦截
router.beforeEach((to, from, next) => {
  const token = uni.getStorageSync('token')
  if (to.meta.requiresAuth && !token) {
    next({ path: '/pages/login/login' })
  } else {
    next()
  }
})

四、总结与展望

Unibest通过标准化的工程化方案，解决了uni-app开发中的痛点问题，尤其适合中大型团队和复杂项目。目前Unibest已支持Vue3+Vite架构，后续将持续优化跨端性能、扩展生态集成（如微前端方案）。

从 useState 到 URLState：前端状态管理的另一种思路

✇掘金 前端
宇余

在 React 开发中，useState 是我们最常用的状态管理工具之一。它轻量、直观，能满足大多数组件级状态管理需求。但在某些场景下，比如列表筛选、分页、多页面共享状态时，单纯使用 useState 会遇到状态丢失、刷新页面重置等问题。这时候，URLState 或许是一个更优雅的解决方案。

一、useState 的「痛点」场景

先来看一个常见的业务场景：实现一个带筛选功能的商品列表页，包含「价格区间」「分类」「排序方式」三个筛选条件。用 useState 实现的代码可能是这样的：


import { useState } from 'react';

function ProductList() {
  // 筛选状态
  const [priceRange, setPriceRange] = useState([0, 1000]);
  const [category, setCategory] = useState('all');
  const [sortBy, setSortBy] = useState('price-asc');

  // 筛选逻辑...
  return (
    <div>
      <FilterPanel 
        priceRange={priceRange}
        onPriceRangeChange={setPriceRange}
        category={category}
        onCategoryChange={setCategory}
        sortBy={sortBy}
        onSortByChange={setSortBy}
      />
      <ProductGrid />
    </div>
  );
}

这段代码看似没问题，但存在三个明显痛点：

  • 页面刷新状态丢失：用户筛选后刷新页面，所有筛选条件会重置为初始值，体验极差。

  • 状态无法共享：如果需要在其他页面（比如商品详情页）回退到筛选后的列表，无法携带筛选状态。

  • 无法书签/分享：用户想把筛选后的结果分享给同事，复制链接过去是未筛选的初始状态。

二、什么是 URLState？为什么要用它？

URLState 是将应用状态存储在 URL 查询参数（Query String）中的状态管理方式。比如上面的筛选场景，使用 URLState 后，URL 可能变成这样：


https://example.com/products?price=0-1000&category=electronics&sort=price-asc

这种方式的核心优势在于：

  • 「刷新不丢状态」：URL 是浏览器的持久化载体，刷新页面参数不会消失。

  • 「天然可共享」：复制 URL 即可分享当前状态，支持书签保存。

  • 「跨页传参简单」：不同页面间通过 URL 即可传递状态，无需依赖全局状态库。

  • 「可回溯」：浏览器的前进/后退按钮能直接回溯状态变更历史。

三、实现 URLState：自定义 useURLState Hook

其实 URLState 的实现并不复杂，核心是通过 URLSearchParams 操作查询参数，并结合 React 的状态更新机制。下面我们封装一个通用的 useURLState Hook。

3.1 核心逻辑拆解

  1. 从 URL 中解析初始状态：通过 new URLSearchParams(window.location.search) 获取查询参数。

  2. 定义状态更新函数：修改状态时，同步更新 URL（使用 history.pushState 避免页面刷新）。

  3. 监听 URL 变化：当用户通过前进/后退按钮切换历史记录时，同步更新组件状态。

3.2 完整实现代码


import { useState, useEffect, useCallback } from 'react';

function useURLState(initialState = {}) {
  // 从 URL 解析状态
  const parseURLState = useCallback(() => {
    const searchParams = new URLSearchParams(window.location.search);
    const state = {};
    
    // 遍历初始状态，从 URL 中提取对应参数
    Object.entries(initialState).forEach(([key, defaultValue]) => {
      const value = searchParams.get(key);
      if (value === null) {
        state[key] = defaultValue;
        return;
      }
      
      // 处理不同类型的默认值（数字、布尔、数组等）
      if (typeof defaultValue === 'number') {
        state[key] = Number(value);
      } else if (typeof defaultValue === 'boolean') {
        state[key] = value === 'true';
      } else if (Array.isArray(defaultValue)) {
        state[key] = value.split('-');
      } else {
        state[key] = value;
      }
    });
    
    return state;
  }, [initialState]);

  // 初始化状态：从 URL 解析或使用初始值
  const [state, setState] = useState(parseURLState());

  // 当 URL 变化时（前进/后退），同步更新状态
  useEffect(() => {
    const handlePopState = () => {
      setState(parseURLState());
    };
    window.addEventListener('popstate', handlePopState);
    return () => window.removeEventListener('popstate', handlePopState);
  }, [parseURLState]);

  // 更新状态并同步到 URL
  const setURLState = useCallback((newState) => {
    const searchParams = new URLSearchParams(window.location.search);
    const nextState = { ...state, ...newState };
    
    // 遍历新状态，更新到 searchParams
    Object.entries(nextState).forEach(([key, value]) => {
      if (value === initialState[key]) {
        // 如果值等于初始值，移除该参数（保持 URL 简洁）
        searchParams.delete(key);
      } else {
        // 数组类型用 "-" 拼接
        const paramValue = Array.isArray(value) ? value.join('-') : String(value);
        searchParams.set(key, paramValue);
      }
    });
    
    // 更新 URL（pushState 不会刷新页面）
    const searchString = searchParams.toString();
    const newUrl = searchString ? `${window.location.pathname}?${searchString}` : window.location.pathname;
    window.history.pushState({}, '', newUrl);
    
    // 更新组件状态
    setState(nextState);
  }, [state, initialState]);

  return [state, setURLState];
}

四、实战：用 URLState 重构商品列表页

有了 useURLState，我们可以轻松重构之前的商品列表页，解决 useState 带来的痛点：


import { useURLState } from './useURLState';

function ProductList() {
  // 用 useURLState 替代 useState，初始状态和之前一致
  const [state, setURLState] = useURLState({
    priceRange: [0, 1000], // 数组类型
    category: 'all',       // 字符串类型
    sortBy: 'price-asc'    // 字符串类型
  });

  const { priceRange, category, sortBy } = state;

  // 筛选条件变更时，调用 setURLState 更新
  const handlePriceChange = (newRange) => {
    setURLState({ priceRange: newRange });
  };

  const handleCategoryChange = (newCategory) => {
    setURLState({ category: newCategory });
  };

  const handleSortChange = (newSort) => {
    setURLState({ sortBy: newSort });
  };

  return (
    <div>
      <FilterPanel 
        priceRange={priceRange}
        onPriceRangeChange={handlePriceChange}
        category={category}
        onCategoryChange={handleCategoryChange}
        sortBy={sortBy}
        onSortByChange={handleSortChange}
      />
      <ProductGrid />
    </div>
  );
}

此时，用户筛选商品后，URL 会自动更新为：


https://example.com/products?priceRange=0-2000&category=electronics&sortBy=price-desc

刷新页面、复制链接分享、后退到上一个筛选状态，都能完美生效！

五、URLState 的适用场景与注意事项

5.1 适用场景

  • 列表筛选、分页、排序等「可分享」的状态。

  • 多步骤表单（如注册流程）的进度状态。

  • 单页应用中的「页面级」状态（如标签页切换）。

5.2 注意事项

  • 不要存储敏感信息：URL 参数会暴露在地址栏、浏览器历史、服务器日志中，密码、token 等敏感信息绝对不能用 URLState。

  • 参数不宜过多/过长：浏览器对 URL 长度有上限（通常 2KB-8KB），复杂状态建议用全局状态库（如 Redux）。

  • 处理特殊类型数据：对于对象等复杂类型，需要先序列化（如 JSON.stringify），但会增加 URL 长度，需谨慎使用。

六、总结

useState 是 React 状态管理的基石，但在「状态持久化」「可分享」场景下存在局限。URLState 作为一种轻量级的补充方案，通过 URL 查询参数实现状态的持久化和共享，无需引入复杂的状态管理库，就能解决很多实际业务问题。

当然，URLState 不是银弹，它和 useState、全局状态库是互补关系。在合适的场景选择合适的工具，才是高效开发的关键。

❌