Flask网站引用本地node_modules下的Chart.js失效，CDN模式运行正常

这类问题是Flask引用本地npm依赖时的高频配置类问题，和你的业务代码逻辑无关，常见触发点集中在三类：

• 版本不匹配引发的API兼容问题
  你用CDN验证正常的业务代码是完全基于Chart.js 2.9.4版本编写的，但执行npm install chart.js --save时，npm默认拉取当前最新的稳定版本（目前为v4.x分支），该分支和2.x版本存在大量不兼容的破坏性更新：全局实例挂载方式、配置项参数结构、接口调用规则都做了重构，就算文件加载成功，原有2.x版本的业务代码也会完全报错失效。
• 引用路径和实际文件不匹配
  两个极易写错的路径细节是高频触发点：
  1. 目录名混淆：npm安装chart.js包后，node_modules下对应的实体文件夹是带小数点的chart.js，不是无点的chartjs，路径写错就会直接返回404。
  2. 文件名混淆：你参照2.x版本官方示例写的引用路径dist/Chart.js，在高版本Chart.js的包结构里根本不存在这个入口文件。当前v3/v4版本的npm包dist目录下，可直接通过script标签引入的UMD格式文件名为chart.umd.js、chart.umd.min.js，不存在大写C开头的Chart.js文件，浏览器请求到不存在的路径就会返回404，根本加载不到Chart.js的脚本。
• 静态文件目录层级错位
  你在static目录内执行了npm init和安装操作，正常生成的node_modules文件夹应该位于static根目录下；但如果中途有路径变动、或者不小心在项目其他层级执行了安装命令，就会导致node_modules实际不在Flask可对外提供静态服务的目录范围内，浏览器请求对应路径时会直接拿到404响应。

按照从易到难的顺序逐一验证即可快速锁定问题：

1. 先确认脚本是否加载成功
   打开浏览器开发者工具的「网络（Network）」面板，刷新页面后找到你引用的本地Chart.js文件请求，查看响应状态码：
   • 如果返回404：说明是路径/文件位置的问题，直接打开本地文件资源管理器，定位项目里node_modules/chart.js/dist/目录下的实际文件名，把script标签里的filename值和实际文件名、目录名完全对齐；同时确认整个node_modules文件夹是在Flask项目的static目录内部，不存在目录错位。
   • 如果返回200：说明文件加载没有问题，继续后续验证。
2. 核对本地安装的Chart.js版本
   打开本地static/node_modules/chart.js/package.json文件，查看version字段对应的版本号：
   • 如果版本号是3.x/4.x：就是版本不兼容问题，直接在static目录下执行npm install chart.js@2.9.4 --save，替换成和之前CDN完全一致的版本即可消除兼容问题。
3. 读取浏览器控制台报错信息
   打开开发者工具的「控制台（Console）」面板，根据具体报错定位问题：
   • 如果报错为Chart is not defined：说明文件没加载成功，回到第一步检查路径正确性。
   • 如果报错为配置项、初始化函数相关的内容：基本可以确定是版本不匹配导致的，换成和CDN一致的版本即可解决。

• 不要直接把整个node_modules目录暴露给静态服务，实际项目里可以只把需要用到的单个Chart.js文件拷贝到static/js/这类固定目录下引用，避免整个依赖目录被公开访问带来的安全风险。
• 安装npm依赖时如果需要固定版本，直接在安装命令后面带上指定版本号，避免默认拉取最新版本带来的无预警兼容问题。

内容的提问来源于stack exchange，提问作者The Candy King