Chart.js 3.x+ 版本中，图例（legend）默认启用但需手动注册插件；若未正确导入并注册 Legend 插件，即使设置 legend: { display: true } 也不会渲染图例。本文详解原因及两种可靠修复方式。
chart.js 3.x+ 版本中，图例（legend）默认启用但需手动注册插件；若未正确导入并注册 `legend` 插件，即使设置 `legend: { display: true }` 也不会渲染图例。本文详解原因及两种可靠修复方式。
在 Chart.js 3.0 及更高版本中，为实现更小的打包体积和模块化设计，所有内置插件（包括图例 Legend、标题 Title、工具提示 Tooltip 等）均不再自动注册。这意味着：即使你在 options.legend 中明确设置了 { display: true }，图例仍不会出现在图表上——因为 Legend 插件根本未被加载到 Chart.js 的全局插件系统中。
这正是你遇到问题的根本原因：你的配置逻辑完全正确，但缺失了关键的插件注册步骤。
✅ 正确解决方案（任选其一）
方案一：按需导入并显式注册 Legend 插件（推荐用于生产环境）
import { Chart, Legend } from 'chart.js';
// 必须显式注册，否则图例不会生效
Chart.register(Legend);✅ 优点：仅打包所需插件，Bundle 体积最小；✅ 清晰可控，适合对性能敏感的项目。
方案二：使用 auto 入口，一键导入全部插件（适合开发/快速验证）
// 替换原来的 import 'chart.js' 或 import { Chart } from 'chart.js'
import Chart from 'chart.js/auto';✅ 优点：开箱即用，无需额外注册；⚠️ 缺点：会引入所有插件（含未使用的），略微增加包体积。
? 补充说明与注意事项
-
options.legend 已被弃用：在 Chart.js 3.8+ 中，options.legend 属于旧式配置，应统一使用 options.plugins.legend（新标准）。建议更新配置如下：
const options = { plugins: { legend: { // ✅ 正确路径：plugins.legend display: true, position: 'right', // 可选：'top', 'bottom', 'left', 'right' labels: { usePointStyle: true, padding: 20 } }, title: { // 同理，title 也需移至 plugins 下 display: true, text: '构建结果分布' }, datalabels: { /* ... */ } } }; 检查控制台报错：若图例仍不显示，请打开浏览器开发者工具，确认是否存在 Chart.register() 相关警告（如 "Legend plugin not registered"），这是最直接的诊断线索。
确保 DOM 元素存在且可渲染：确认 #chartContainer 已挂载、宽高非零（例如添加 CSS #chartContainer { width: 400px; height: 400px; }）。
✅ 完整可运行示例（基于方案一）
<canvas id="chartContainer"></canvas>
<script type="module">
import { Chart, Legend } from 'chart.js';
Chart.register(Legend); // ? 关键！必须注册
const ctx = document.getElementById('chartContainer').getContext('2d');
const myChart = new Chart(ctx, {
type: 'doughnut',
data: {
datasets: [{
data: [72, 28],
labels: ['Successes', 'Failures'],
backgroundColor: ['green', 'red'],
borderColor: '#fff'
}]
},
options: {
plugins: {
legend: { display: true, position: 'right' },
title: { display: true, text: '构建成功率分析' }
}
}
});
</script>✅ 总结：图例不可见 ≠ 配置错误，而是插件未注册。牢记 Chart.js 3+ 的“按需注册”原则——配置是声明“要什么”，注册才是保证“能用什么”。优先采用 import { Chart, Legend } from 'chart.js'; Chart.register(Legend); 组合，兼顾可靠性与工程规范性。
