微信小程序集成 Day.js 插件的完整解决方案

前言在微信小程序开发中Day.js 是一个非常流行的轻量级日期时间处理库。然而在实际使用过程中我们发现微信小程序的 npm 构建工具在处理 Day.js 的插件模块时存在兼容性问题。本文将详细记录问题的排查过程、解决方案以及最佳实践。问题背景在项目中引入 Day.js 及其插件duration、relativeTime、weekday、isBetween后在微信开发者工具中构建 npm 时遇到以下问题插件目录缺失构建后的miniprogram_npm/dayjs/目录下没有plugin子目录模块加载失败运行时报错module dayjs/plugin/duration.js is not defined路径解析错误尝试使用不同的引用路径都未能解决问题环境配置软件版本操作系统: macOS Sequoia 15.6.1 (Darwin Kernel Version 24G90, arm64)Shell: zsh微信开发者工具: 2.01.2510260 darwin-arm64微信小程序基础库: 3.13.2 / 2.19.4Node.js: v23.11.0npm: 10.9.2项目依赖wxapp/package.json{name:wxapp,version:1.0.0,description:微信小程序,main:app.js,dependencies:{dayjs:^1.11.20,...},devDependencies:{eslint:^8.0.0,eslint-config-standard:^17.0.0,eslint-plugin-import:^2.25.0,eslint-plugin-node:^11.1.0,eslint-plugin-promise:^6.0.0,miniprogram-api-typings:^3.9.0},...}小程序配置wxapp/project.config.json{setting:{es6:true,packNpmManually:true,packNpmRelationList:[{packageJsonPath:./package.json,miniprogramNpmDistDir:./}],nodeModules:true,libVersion:3.13.2,...},...}问题复现与排查初始代码utils/date-time.jsconstdayjsrequire(dayjs)/** * 扩展 duration 插件 */constdurationrequire(dayjs/plugin/duration.js)dayjs.extend(duration)/** * 扩展 relativeTime 插件相对时间 */constrelativeTimerequire(dayjs/plugin/relativeTime.js)dayjs.extend(relativeTime)/** * 扩展 weekday 插件星期 */constweekdayrequire(dayjs/plugin/weekday.js)dayjs.extend(weekday)/** * 扩展 isBetween 插件判断是否在两个日期之间 */constisBetweenrequire(dayjs/plugin/isBetween.js)dayjs.extend(isBetween)/** * 日期时间工具类 */constDateTimeUtil{format(date,formatYYYY-MM-DD HH:mm:ss){if(!date)returnreturndayjs(date).format(format)},// ... 其他方法}module.exportsDateTimeUtil问题现象执行微信开发者工具的构建 npm后检查miniprogram_npm/dayjs/目录$ls-lhminiprogram_npm/dayjs total40-rw-r--r--1yakoo5 staff8.4K32122:48 index.js -rw-r--r--1yakoo5 staff7.3K32122:48 index.js.map关键发现miniprogram_npm/dayjs/目录下没有plugin子目录导致插件文件无法被正确加载。运行时的错误信息页面【pages/paper-detail/paper-detail]错误: Error: module dayjs/plugin/duration.js is not defined, require args is dayjs/plugin/duration at q (VM2704 WASubContext.js:1) at n (VM2704 WASubContext.js:1) at date-time.js? [sm]:10解决方案经过实际测试和验证我们找到了两种有效的解决方案。方案一手动复制插件到 miniprogram_npm 目录适用场景希望保持 npm 标准引用方式不修改代码中的 require 路径。步骤 1创建插件目录cdwxappmkdir-pminiprogram_npm/dayjs/plugin步骤 2复制插件文件# 从 node_modules 复制所需的插件文件到 miniprogram_npm/dayjs/plugin/cp-vfnode_modules/dayjs/plugin/duration.js miniprogram_npm/dayjs/plugincp-vfnode_modules/dayjs/plugin/isBetween.js miniprogram_npm/dayjs/plugincp-vfnode_modules/dayjs/plugin/relativeTime.js miniprogram_npm/dayjs/plugincp-vfnode_modules/dayjs/plugin/weekday.js miniprogram_npm/dayjs/plugin步骤 3验证目录结构$ls-lhminiprogram_npm/dayjs/plugin total40-rw-r--r--1yakoo5 staff4.7K32122:48 duration.js -rw-r--r--1yakoo5 staff 546B32122:48 isBetween.js -rw-r--r--1yakoo5 staff1.4K32122:48 relativeTime.js -rw-r--r--1yakoo5 staff 427B32122:48 weekday.js步骤 4重新编译在微信开发者工具中选择工具 编译验证问题是否解决。方案二本地化插件文件推荐✅适用场景希望完全控制依赖便于版本管理和团队协作。步骤 1创建插件目录cdwxappmkdir-putils/plugins/dayjs步骤 2复制插件文件# 从 node_modules 复制所需的插件文件到 utils/plugins/dayjs/cp-vfnode_modules/dayjs/plugin/duration.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/isBetween.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/relativeTime.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/weekday.js utils/plugins/dayjs步骤 3修改 utils/date-time.js/** * 日期时间工具类 * 基于 Day.js 实现 */constdayjsrequire(dayjs)/** * 扩展 duration 插件 */constdurationrequire(./plugins/dayjs/duration.js)dayjs.extend(duration)/** * 扩展 relativeTime 插件相对时间 */constrelativeTimerequire(./plugins/dayjs/relativeTime.js)dayjs.extend(relativeTime)/** * 扩展 weekday 插件星期 */constweekdayrequire(./plugins/dayjs/weekday.js)dayjs.extend(weekday)/** * 扩展 isBetween 插件判断是否在两个日期之间 */constisBetweenrequire(./plugins/dayjs/isBetween.js)dayjs.extend(isBetween)/** * 日期时间工具类 */constDateTimeUtil{format(date,formatYYYY-MM-DD HH:mm:ss){if(!date)returnreturndayjs(date).format(format)},// ... 其他方法}module.exportsDateTimeUtil步骤 4构建 npm 并重新编译# 在微信开发者工具中依次执行# 1. 工具 清除缓存 全部清除# 2. 工具 构建 npm# 3. 工具 编译方案对比特性方案一复制到 miniprogram_npm方案二本地化插件推荐代码修改无需修改代码需要修改 require 路径版本控制不纳入版本控制临时文件纳入版本控制团队协作每个开发者需要手动复制自动同步可维护性较低较高npm 构建仍然需要仍然需要推荐度⭐⭐⭐⭐⭐⭐⭐⭐微信小程序基础库版本的影响在实际测试中我们发现不同的基础库版本对 Day.js 插件的支持存在差异测试场景基础库版本项目配置最低基础库版本构建结果插件目录3.13.2libVersion: “3.13.2”✅ 成功缺失 plugin 目录3.13.2libVersion: “2.19.4”✅ 成功缺失 plugin 目录结论无论使用哪个基础库版本3.13.2 或 2.19.4微信小程序的 npm 构建工具都无法自动处理 Day.js 的插件子目录。这是一个普遍存在的问题与基础库版本无关。问题根因分析1. 微信小程序 npm 构建工具的限制微信小程序的 npm 构建工具在处理某些 npm 包的子模块时存在兼容性问题路径解析问题当使用require(dayjs/plugin/duration.js)时构建工具无法正确解析插件子模块的路径构建产物问题构建后的miniprogram_npm/dayjs/目录下缺少plugin子目录2. Day.js 插件文件的格式Day.js 的插件文件是 UMD 模块格式并且是压缩后的单行代码!function(t,s){objecttypeofexportsundefined!typeofmodule?module.exportss():functiontypeofdefinedefine(s):(tundefined!typeofglobalThis?globalThis:t||self).dayjs_plugin_durations()}(this,(function(){use strict;vart,s,n1e3,...(大量压缩代码)...补充说明虽然插件文件是压缩后的单行代码但在实际测试中并未出现之前偶现的语法错误“Missing semicolon”。只要文件被正确复制到指定目录微信小程序的模块加载器可以正常解析。3. 微信小程序的模块解析机制微信小程序的require()机制与 Node.js 的 CommonJS 规范存在差异不支持 npm 包的子模块路径require(package-name/submodule)在小程序中可能无法正确解析需要明确的相对路径需要使用相对于当前文件的明确路径最佳实践建议1. 项目目录结构wxapp/ ├── package.json ├── project.config.json ├── utils/ │ ├── plugins/ # 本地化的第三方插件如果使用方案二 │ │ └── dayjs/ # Day.js 插件 │ │ ├── duration.js │ │ ├── relativeTime.js │ │ ├── weekday.js │ │ └── isBetween.js │ ├── date-time.js # 日期时间工具类 │ └── ... ├── miniprogram_npm/ # npm 构建产物 │ └── dayjs/ │ ├── index.js │ ├── index.js.map │ ├── package.json │ └── plugin/ # 手动创建的插件目录如果使用方案一 │ ├── duration.js │ ├── relativeTime.js │ ├── weekday.js │ └── isBetween.js ├── node_modules/ # npm 依赖 │ └── dayjs/ │ ├── plugin/ │ ├── esm/ │ └── ... └── ...2. 依赖管理纳入版本控制将本地化的插件文件纳入 Git 版本控制记录版本信息在代码注释中记录对应的 dayjs 版本号按需引入只复制项目实际使用的插件文件减少项目体积3. 构建流程在引入新的 npm 包或更新 dayjs 版本时建议按以下步骤操作# 1. 清理旧的构建产物cdwxapprm-rfnode_modulesrm-rfminiprogram_npm# 2. 安装依赖npminstall# 3. 复制插件文件如果使用方案二mkdir-putils/plugins/dayjscp-vfnode_modules/dayjs/plugin/duration.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/isBetween.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/relativeTime.js utils/plugins/dayjscp-vfnode_modules/dayjs/plugin/weekday.js utils/plugins/dayjs# 4. 在微信开发者工具中构建 npm# 工具 清除缓存 全部清除# 工具 构建 npm4. 团队协作建议编写文档在项目的 README 或开发文档中记录插件引入的步骤自动化脚本可以编写 npm script 自动化插件复制过程代码审查在 Pull Request 中检查插件文件是否正确更新自动化脚本示例为了简化插件文件的管理可以创建一个自动化脚本scripts/copy-dayjs-plugins.sh#!/bin/bash# 复制 Day.js 插件文件的自动化脚本cd$(dirname$0)/..echo开始复制 Day.js 插件文件...# 创建插件目录mkdir-putils/plugins/dayjs# 复制插件文件plugins(duration.jsrelativeTime.jsweekday.jsisBetween.js)forpluginin${plugins[]};doif[-fnode_modules/dayjs/plugin/$plugin];thencp-vfnode_modules/dayjs/plugin/$pluginutils/plugins/dayjs/echo✓ 已复制:$pluginelseecho✗ 文件不存在: node_modules/dayjs/plugin/$pluginfidoneechoDay.js 插件文件复制完成在package.json中添加脚本{scripts:{copy:dayjs:bash scripts/copy-dayjs-plugins.sh,postinstall:npm run copy:dayjs}}这样在执行npm install后会自动复制插件文件。常见问题 FAQQ1: 为什么不直接使用 require(‘dayjs/plugin/duration’)A: 微信小程序的 npm 构建工具无法正确处理这种子模块路径导致plugin目录不被复制到miniprogram_npm下。Q2: 方案一和方案二哪个更好A: 推荐使用方案二本地化插件因为纳入版本控制便于团队协作不依赖于构建产物的临时性更容易进行版本管理Q3: 更新 dayjs 版本时需要注意什么A: 需要检查新版本中的插件文件是否有变化并重新复制插件文件。建议使用自动化脚本减少人为错误。Q4: 是否需要将复制的插件文件提交到 GitA: 如果使用方案二本地化插件建议提交到 Git。如果使用方案一复制到 miniprogram_npm不推荐提交应该将其添加到.gitignore。Q5: 是否可以使用 esm 版本的插件A: 微信小程序目前不完全支持 ES6 模块语法建议使用 CommonJS 版本的插件文件。总结微信小程序的 npm 构建工具在处理 Day.js 插件时存在兼容性问题主要表现为plugin子目录缺失。通过手动复制插件文件到指定目录可以成功解决问题。核心要点问题根源微信小程序 npm 构建工具无法正确处理 Day.js 的插件子目录解决方案手动复制插件文件到utils/plugins/dayjs/或miniprogram_npm/dayjs/plugin/推荐方案使用方案二本地化插件纳入版本控制版本影响问题与基础库版本无关3.13.2 和 2.19.4 都存在此问题最佳实践自动化插件复制流程纳入版本控制编写团队文档通过本文提供的解决方案和最佳实践可以避免在微信小程序项目中遇到类似问题提高开发效率和团队协作效率。参考资料Day.js 官方文档微信小程序 npm 支持微信小程序模块加载机制文档创建日期: 2026-03-21最后更新日期: 2026-03-21文档版本: 1.0测试环境: 微信小程序基础库 3.13.2 / 2.19.4注本文基于实际项目经验整理希望对遇到类似问题的开发者有所帮助。如有疑问或建议欢迎交流讨论。