bootstrap 5 不支持原生日期选择器，需手动集成 jquery 插件（如 bootstrap-datepicker），但必须显式引入 jquery（推荐 3.6.x），确保 dom 就绪后初始化，严格匹配 format 与 value 格式，并注意资源加载顺序和时区处理。
Bootstrap 5 官方不提供日期选择器，bootstrap-datepicker、bootstrap-datetimepicker 这类插件必须手动集成，且不能直接用 Bootstrap 5 的 JS 工具类（如 Modal 或 Dropdown）控制其行为——它们是独立的 jQuery 插件，依赖链和初始化时机稍有偏差就会失效。
确认你用的是 Bootstrap 5 还是 4
这是最容易卡住的第一步。Bootstrap 5 彻底移除了 jQuery 依赖，而所有主流日期插件（bootstrap-datepicker、bootstrap-datetimepicker、daterangepicker）仍基于 jQuery。如果你项目已升级到 Bootstrap 5 但没引入 jQuery，插件会直接报 $ is not defined 错误。
- 必须显式引入 jQuery（推荐 3.6.x，避免 4.x 不兼容）
- Bootstrap 5 CSS 可照常使用，但 JS 部分（
bootstrap.bundle.min.js）只管自己的组件，不接管插件 - 若用 Vite/Webpack 等构建工具，需确保 jQuery 全局可用（例如通过
window.$ = window.jQuery = require('jquery')或配置ProvidePlugin）
input 元素必须带 class 且不可被动态替换
插件靠 class 名触发初始化，比如 $('.datepicker') 会查找所有含 datepicker class 的 <input>。但如果你在 Vue/React 中用 v-model 或 useState 控制表单，或用 JS 动态生成 input 标签，class 可能存在但 DOM 尚未就绪，导致 .datepicker() 执行时找不到目标。
- 初始化代码必须放在 DOM ready 后，例如
$(document).ready(() => { ... })或DOMContentLoaded事件内 - 避免对已初始化过的 input 重复调用
.datepicker()，否则会创建多个实例，UI 错乱 - 若 input 是异步加载（如 Tab 切换后渲染），需手动调用
$('.new-input').datepicker(options) - 不要用
innerHTML = '...'替换整个表单区域，会销毁已绑定的插件实例
format 和 value 格式必须严格匹配
插件显示格式（format）和实际写入 input 的值（value）是两回事。很多问题表现为“选了日期但提交时为空”或“初始值不显示”，根源往往是格式不一致。
-
bootstrap-datepicker默认format: 'mm/dd/yyyy'，但后端通常要yyyy-mm-dd；必须显式设成后者，并确保 input 的初始value也是该格式（如<input value="2026-09-04">） -
bootstrap-datetimepicker的format使用 moment.js 语法：'YYYY-MM-DD HH:mm'，大小写敏感，hh（12小时制）和HH（24小时制）不能混用 - 若 input 值含时区（如
2026-09-04T01:28:00+08:00），插件可能无法解析，建议服务端返回无时区 ISO 格式（2026-09-04T01:28:00）或纯日期字符串
Thymeleaf 或其他模板引擎中注意资源加载顺序
在若依（RuoYi）等基于 Thymeleaf 的后台系统里，CSS/JS 加载位置不对会导致样式错位或功能失效，尤其当页面 layout 把 JS 放在 底部，而插件初始化代码写在局部 HTML 片段里时。
- CSS 必须在
中引入（bootstrap-datepicker.css要在 Bootstrap CSS 之后） - jQuery 和插件 JS 必须在
bootstrap.bundle.min.js之后、初始化代码之前 - Thymeleaf 的
th:fragment若包含初始化脚本，需确保它最终渲染在所有依赖资源加载完毕之后；更稳妥做法是把初始化逻辑统一收口到全局 JS 文件中 - 检查浏览器开发者工具的 Network 面板，确认
bootstrap-datepicker.js等文件返回 200，路径别写成/css/bootstrap-datepicker.js（常见错误）
最常被忽略的一点：插件初始化后，input 的 value 是字符串，不是 Date 对象；如果后续要用 JS 做计算（比如判断是否晚于今天），别直接拿 input.value 去 new Date() —— 不同格式解析结果可能出错，应优先用插件提供的方法，如 $('#dp').datepicker('getDate') 获取原生 Date 实例。
