Fullcalendar v5 dayGridMonth视图偶现Invalid date显示异常

算力阿峰

2026-8-26

问题核心诱因

最高概率的触发原因是法语locale资源加载时序竞争：FullCalendar v5的非英文locale资源默认不包含在核心库中，配置locale: 'fr'时，如果初始化Calendar实例的时机早于法语locale脚本的加载完成时间，核心库找不到匹配的日期解析、格式化规则，就会导致所有日期相关逻辑失效，整个月视图网格全部渲染为"Invalid date"。这个问题偶发的根本原因是网络加载速度不稳定：locale包加载快于业务初始化逻辑时功能正常，加载慢于初始化时就触发异常，和页面重载时偶发故障的现象完全吻合。
次要触发原因：传入的事件数组存在脏日期数据。哪怕控制台打印看到事件数组整体已填充，只要其中某一条事件的start/end字段是空字符串、null、不符合ISO 8601格式的非法值，在特定解析顺序下就可能打断整个视图的日期渲染流程，触发全局日期报错。
低概率诱因：页面内存在多版本日期处理库冲突。如果页面同时引入了多个版本的moment.js、dayjs，和FullCalendar自带的日期模块产生冲突，也会偶发日期解析失效。

可行修复方案

彻底解决locale加载时序问题
如果是ES模块方式引入FullCalendar，不要给locale传字符串'fr'，直接显式导入法语locale对象传入配置，从根源上避免找不到locale资源的问题：

// 显式导入核心库、所需插件和法语locale
import { Calendar } from '@fullcalendar/core';
import frLocale from '@fullcalendar/core/locales/fr';
import dayGridPlugin from '@fullcalendar/daygrid';

const calendar = new Calendar(calendarEl, {
  plugins: [dayGridPlugin],
  locale: frLocale, // 直接传入导入的locale对象，不要传字符串
  initialView: 'dayGridMonth',
  firstDay: 1,
  headerToolbar: {
    left: 'prev',
    center: 'title',
    right: 'next'
  },
  height: 'auto',
  events: currentCalendarEvents,
  eventOrder: 'eventId'
});

如果是CDN脚本引入的方式，确保法语locale的script标签放在FullCalendar核心库标签之后、业务初始化代码之前，不要用动态异步插入script的方式加载locale资源，保证初始化执行时locale已经完成注册。

初始化前做事件数据清洗
不要直接把AJAX返回的原始数组传入events参数，初始化前先遍历过滤掉携带非法日期的脏数据：

const validEvents = currentCalendarEvents.filter(event => {
  if (!event.start) return false;
  return !Number.isNaN(new Date(event.start).getTime());
});
// 初始化配置中events传入清洗后的validEvents

保证DOM就绪后再执行渲染
把日历初始化和渲染逻辑放在DOMContentLoaded回调里执行，避免DOM容器未加载完成导致的渲染异常：

document.addEventListener('DOMContentLoaded', function() {
  const calendarEl = document.getElementById('calendar');
  // 此处放入上述初始化逻辑
  calendar.render();
});

排查依赖冲突
如果以上操作后故障仍存在，检查页面中是否全局引入了多余的日期处理库，移除和FullCalendar内置日期模块冲突的多版本moment、dayjs资源即可。

内容的提问来源于stack exchange，提问作者Tiak