vtils

vtils#

资源概述#

vtils 是一款面向业务的 JavaScript/TypeScript 实用程序库，由开发者 fjc0k（偏右）创建并维护。它基于社区优质库（Lodash、date-fns、react-use、type-fest、ts-essentials、yup 等）进行补充和封装，提供基础工具、日期时间工具、React Hooks、验证器、类型工具和小程序专用工具六大模块。项目在 GitHub 获得 252 星标，npm 发布了高达 546 个版本（v4.138.0），展现了长期持续的维护投入。支持浏览器、Node.js、小程序（Taro 3）、Deno 多平台运行，为每个工具都添加了注释和测试。截至 2026 年 4 月仍在持续更新。

设计规范#

六大子模块：vtils（基础工具如 EventBus、md5、base64Encode）、vtils/date（日期工具如 formatRelative）、vtils/react（React Hooks 如 useToggle、useScrollLoadMore）、vtils/validator（基于 yup 的验证器）、vtils/types（TypeScript 类型工具如 OmitStrict、PartialDeep）、vtils/mp（小程序专用工具如 getTopBarInfo、navigatePageTo）
Tree Shaking 友好：ESM 产物，按需引入，不会引入未使用代码
TypeScript 原生：所有工具均用 TypeScript 编写，类型定义完整
测试完善：每个工具都有对应测试，测试覆盖率报告公开可查

审核规范#

不适用（工具库，非平台）。

开发指南#

快速上手#

code

// 基础工具
import { wait, isNumber, EventBus, base64Encode, md5 } from 'vtils'

// 日期时间工具
import { formatRelative, subDays, zhCN } from 'vtils/date'

// React 工具
import { useClassName, useToggle, useScrollLoadMore } from 'vtils/react'

// 验证工具
import { yup } from 'vtils/validator'

// 类型工具
import { OmitStrict, LiteralUnion, PartialDeep } from 'vtils/types'

// 小程序工具
import { getTopBarInfo, navigatePageTo, redirectPageTo } from 'vtils/mp'

在 Taro 3 中使用#

code

// config/index.js
const config = {
  mini: {
    webpackChain(config) {
      // 该插件会影响 resolve.extensions 的表现，需删除
      config.resolve.plugins.delete('MultiPlatformPlugin')
      // 支持 .taro.js 后缀
      config.resolve.extensions
        .prepend('.taro.js')
        .prepend('.taro.ts')
        .prepend('.taro.tsx')
    }
  }
}

小程序专用工具#

code

import { getTopBarInfo, navigatePageTo, cache } from 'vtils/mp'

// 获取顶部导航栏信息（安全区高度、状态栏高度等）
const { statusBarHeight, navBarHeight } = getTopBarInfo()

// 封装的页面跳转（自动处理参数）
navigatePageTo({ url: '/pages/detail/index', params: { id: 123 } })

// 小程序本地缓存
cache.set('key', { data: 'value' })
const value = cache.get('key')

常见陷阱#

Taro 3 需额外配置：必须修改 webpackChain 删除 MultiPlatformPlugin 并添加 .taro.js 后缀，否则 vtils/mp 模块无法正确解析
子模块独立安装：各子模块（date/react/validator/types/mp）随主包一起安装，但导入路径不同，需按文档使用正确路径
版本兼容：v4.x 与 v3.x API 有较大变化，升级时需参考迁移指南
包体积：虽然支持 Tree Shaking，但全量引入仍较大，建议按需导入具体函数

生态资源#

配套工具#

tbify（同作者）：淘宝镜像加速器，国内安装 vtils 更快
yup：vtils/validator 基于 yup 封装

社区资源#

官方文档：https://fjc0k.github.io/vtils/v4/
测试覆盖率：https://fjc0k.github.io/vtils/v4-coverage/

版本更新#

v4.138.0（最新）：npm 546 个版本，长期高频迭代，最近修改 2026-04-14
v4 大版本重构：模块化设计（6 大子模块）、TypeScript 全面支持、Tree Shaking 优化
持续补充业务常用工具函数，测试覆盖完善
支持 Taro 3+ / Deno / Node.js / 浏览器多平台

详细文档

vtils#

资源概述#

设计规范#

审核规范#

开发指南#

快速上手#

在 Taro 3 中使用#

小程序专用工具#

常见陷阱#

生态资源#

推荐框架#

配套工具#

社区资源#

版本更新#