升级到 Chart.js 4.4.1 时需使用 UMD 构建版本并确保插件兼容，否则会因全局 Chart 未定义、ES 模块语法错误或插件依赖缺失而报错。
升级到 chart.js 4.4.1 时需使用 umd 构建版本并确保插件兼容，否则会因全局 `chart` 未定义、es 模块语法错误或插件依赖缺失而报错。
Chart.js 自 v3.x 起彻底重构为 ES 模块（ESM）优先架构，v4.x 进一步移除了对传统 <script> 全局变量注入的默认支持。这意味着：<strong>直接通过 <script src="chart.min.js"> 引入官方发布的 chart.min.js（即 ESM 版本）将无法在浏览器中直接访问 Chart 全局对象，从而触发 Uncaught ReferenceError: Chart is not defined。</script>
✅ 正确引入方式（浏览器环境）
必须使用 UMD（Universal Module Definition）构建版本，它同时支持全局变量、AMD 和 CommonJS，可在任何传统脚本环境中安全使用：
<!-- 推荐：使用 UMD 版本（含全局 Chart 对象） --> <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script><script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-datalabels@2.2.0/dist/chartjs-plugin-datalabels.min.js"></script><canvas id="myChart" height="60"></canvas>
⚠️ 注意：
- ❌ 避免使用 chart.min.js（ESM）、chart.esm.min.js 或 chart.cjs.min.js；
- ✅ 唯一适用于纯 HTML <script> 场景的是 chart.umd.min.js； </script>
- CDN 来源推荐 cdn.jsdelivr.net（稳定、支持版本精确锁定），而非 cdnjs.com（其 v4.x UMD 文件可能未同步或路径不规范）。
✅ 插件兼容性关键点
Chart.js v4 要求插件必须显式注册，且版本需严格匹配。chartjs-plugin-datalabels@2.2.0 是目前唯一正式支持 v4 的稳定版本（v1.x 不兼容）。注册方式保持不变（自动注册），但前提是：
- Chart.js UMD 版本已加载（提供全局 Chart）；
- 插件脚本在 Chart.js 之后加载；
- 插件自身也需使用 UMD 兼容构建（上述 CDN 链接即满足）。
✅ 完整可运行示例
<title>Chart.js v4.4.1 Bar Chart</title><canvas id="myChart" width="400" height="200"></canvas><!-- 顺序不可颠倒：先 Chart.js UMD，再插件 --><script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script><script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-datalabels@2.2.0/dist/chartjs-plugin-datalabels.min.js"></script><script>
const data = {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
datasets: [{
label: 'Weekly Sales',
data: [18, 12, 6, 9, 12, 3, 9],
backgroundColor: [
'rgba(255, 26, 104, 0.2)',
'rgba(54, 162, 235, 0.2)',
'rgba(255, 206, 86, 0.2)',
'rgba(75, 192, 192, 0.2)',
'rgba(153, 102, 255, 0.2)',
'rgba(255, 159, 64, 0.2)',
'rgba(0, 0, 0, 0.2)'
],
borderColor: [
'rgba(255, 26, 104, 1)',
'rgba(54, 162, 235, 1)',
'rgba(255, 206, 86, 1)',
'rgba(75, 192, 192, 1)',
'rgba(153, 102, 255, 1)',
'rgba(255, 159, 64, 1)',
'rgba(0, 0, 0, 1)'
],
borderWidth: 1
}]
};
const config = {
type: 'bar',
data,
options: {
scales: {
y: { beginAtZero: true }
}
}
};
const myChart = new Chart(document.getElementById('myChart'), config);
</script>
? 常见错误排查清单
| 错误现象 | 根本原因 | 解决方案 |
|---|---|---|
| Chart is not defined | 加载了 chart.min.js（ESM）而非 chart.umd.min.js | 替换为 .umd.min.js 路径 |
| Cannot use import statement outside a module | 浏览器尝试解析 ESM 文件为普通 script | 确保使用 UMD 版本，且无 type="module" 属性 |
| Cannot read properties of undefined (reading 'helpers') | 插件版本过低（如 v1.x）或未正确加载 Chart.js | 升级插件至 @2.2.0+，检查加载顺序与网络状态 |
✅ 总结：Chart.js v4+ 在浏览器中“开箱即用”的唯一可靠路径是 UMD 构建 + 正确 CDN 链接 + 插件版本对齐。放弃旧版 <script> 直接迁移思维，拥抱模块化生态的同时，善用 UMD 作为兼容桥梁。</script>
