在 Vue 3 项目里处理日期和时间,最忌讳的就是在业务组件中到处调用 dayjs().format()。这种方式在小型项目里看不出问题,一旦出现产品级需求,比如统一显示为 2024/01/05 09:30 或处理相对时间,散落的格式化代码就会成为维护负担。二次封装 dayjs 并不是多此一举,而是把格式、语言、时区和异常兜底集中起来。下面从工具模块设计、组合式函数接入、格式化规则三个层面展开。

一、为什么选择 dayjs 以及为什么需要二次封装
Vue 3 项目选择 dayjs 的首要原因是体积。dayjs 核心包约 2KB,而 moment 打包后要大得多,并且 moment 官方已不再推荐用于新项目。dayjs 的 API 设计与 moment 高度相似,迁移成本低,同时它是一个不可变库,每次链式操作都会返回新的日期对象,不会污染原始值。这个特性在 Vue 3 的响应式数据里尤为重要,因为原始日期对象的修改不容易被追踪,反而容易产生隐性 bug。
二次封装的核心不是包一层 API 那么简单。它要解决三个问题:第一,统一默认输出格式,避免不同页面出现 2024-1-5、2024/01/05、2024年1月5日 等混用;第二,集中配置中文语言包和插件,不让每个组件重复引入;第三,统一空值和无效日期的兜底策略。只要把这些逻辑放在一个模块里,后续调整时只改一处即可。
例如安装依赖后,先在工具文件里引入 dayjs,并按需加载相对时间插件 relativeTime 和 UTC 插件 utc。插件只有在 dayjs.extend() 注册后才会生效,这样可以保持运行时体积可控。
npm install dayjs
二、封装一个可复用的日期工具模块
封装日期工具模块时,建议把配置与函数分开。配置文件负责初始化 dayjs,包括 dayjs.extend() 和 dayjs.locale('zh-cn')。业务函数只做两件事:接收一个可能的日期值,先用 dayjs(value) 转换,再判断 isValid(),有效则格式化,无效则返回空字符串或指定占位符。这样可以避免界面出现英文的 Invalid Date,也能让调用方省去大量判断。
以 formatDate 为例,不要直接 return dayjs(value).format(pattern),因为当 value 是 null、空字符串或无效时间时,format() 会抛出异常或返回奇怪结果。先验证再格式化,才能保证组件渲染稳定。另一个常用函数是 formatRelative,它依赖 relativeTime 插件,配合中文 locale 会显示几分钟前、三天前等自然语言。
下面是一份相对完整的模块代码,包含日期、日期时间、相对时间和天数差计算。导出时同时提供具名函数和默认对象,既方便按需引入,也可以在需要时整体导入。
import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'
import utc from 'dayjs/plugin/utc'
import 'dayjs/locale/zh-cn'
dayjs.extend(relativeTime)
dayjs.extend(utc)
dayjs.locale('zh-cn')
export const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD'
export const DEFAULT_DATETIME_FORMAT = 'YYYY-MM-DD HH:mm:ss'
export function isValidDate(value) {
return dayjs(value).isValid()
}
export function formatDate(value, pattern = DEFAULT_DATE_FORMAT) {
const date = dayjs(value)
return date.isValid() ? date.format(pattern) : ''
}
export function formatDateTime(value) {
return formatDate(value, DEFAULT_DATETIME_FORMAT)
}
export function formatRelative(value) {
const date = dayjs(value)
return date.isValid() ? date.fromNow() : ''
}
export function diffDays(start, end) {
const startDay = dayjs(start)
const endDay = dayjs(end)
if (!startDay.isValid() || !endDay.isValid()) return 0
return endDay.diff(startDay, 'day')
}
export default {
formatDate,
formatDateTime,
formatRelative,
diffDays,
isValidDate
}
三、在 Vue 3 组件与组合式函数中使用
在 Vue 3 组件中使用这些函数时,推荐用 <script setup> 语法直接导入。日期展示通常与 props 或接口返回的字符串绑定,所以可以用 computed 把格式化结果缓存起来,避免模板每次更新都重新执行一次格式化。尤其是相对时间,它依赖当前时间,建议在需要更新时手动触发,不要把它放在频繁刷新的 computed 中。
另一个常见做法是把 formatDate 挂载到 app.config.globalProperties 上,这样可以在模板中直接用 $formatDate 调用。这个方式对选项式 API 代码比较友好,但在组合式 API 中无法通过 this 直接访问,需要结合 getCurrentInstance 或者干脆显式导入。个人更建议显式导入,因为类型提示和依赖关系更清晰。
下面的组件示例接收一个创建时间字符串,展示标准日期和相对时间。注意不要把 formatRelative 的返回值保存到响应式变量后再反复赋值,而是用 computed 直接根据原始数据生成展示值。
<script setup>
import { computed } from 'vue'
import { formatDate, formatRelative } from '@/utils/date'
const props = defineProps({
createdAt: {
type: String,
required: true
}
})
const displayDate = computed(() => formatDate(props.createdAt, 'YYYY年MM月DD日'))
const relativeText = computed(() => formatRelative(props.createdAt))
</script>
<template>
<div>
<span>{{ displayDate }}</span>
<span>{{ relativeText }}</span>
</div>
</template>
四、格式化模板与细节避坑
dayjs 的格式化 token 不难记,但有几个地方容易踩坑。年份使用大写 YYYY,月份使用大写 MM,分钟使用小写 mm。如果写成 yyyy-mm-dd,dayjs 不会按预期输出,因为 yyyy 不是有效 token,会保持原样。常用组合可以参考下面表格。
| 格式 | 输出示例 | 说明 |
|---|---|---|
| YYYY-MM-DD | 2024-01-05 | 标准日期 |
| YYYY-MM-DD HH:mm:ss | 2024-01-05 09:30:45 | 标准日期时间 |
| YYYY年MM月DD日 | 2024年01月05日 | 中文日期 |
| YYYY/MM/DD HH:mm | 2024/01/05 09:30 | 短日期时间 |
国际化方面,必须显式 import 'dayjs/locale/zh-cn' 并调用 dayjs.locale('zh-cn'),否则 fromNow() 输出的内容仍然是英文。对于需要处理 UTC 时间的场景,可以先 dayjs.utc(value) 再 .local() 转成本地时间。要注意 dayjs 内置的 utc 插件不能处理任意时区名称,例如想用 Asia/Shanghai,需要额外的 timezone 插件,这会增加一定体积,所以只在真正需要时引入。
响应式数据是 Vue 3 中很容易被忽略的日期坑。不要直接把 dayjs 对象放进 reactive 或 ref 中,因为 Vue 的代理会改变对象行为,可能导致方法失效或者触发不必要的更新。推荐在数据层保存 ISO 字符串或时间戳,展示层再通过工具函数转换。下面是一个错误和推荐的对比。
import { reactive } from 'vue'
import dayjs from 'dayjs'
// 不推荐:dayjs 对象被 reactive 代理
const state = reactive({
time: dayjs()
})
// 推荐:保存原始字符串或时间戳
const betterState = reactive({
time: new Date().toISOString()
})
除了这些细节,封装后的日期模块应当保持纯函数特性:同一输入永远得到同一输出,不要在内部修改全局状态。这样在单元测试中也能直接断言格式化结果。若项目中有多种日期格式需求,可以继续在模块里扩展 formatMonth、formatWeek 等函数,不必在每个页面复制模板字符串。