Rails 6 中如何正确引入第三方 face-api.min.js 文件？

核心原因 #

Rails 6 默认使用 Webpacker 管理前端资源，app/javascript/packs 目录下的文件会被作为独立模块打包，带有自身的作用域隔离机制，不会像纯 HTML 中用 <script> 标签直接引入的脚本那样，把内部定义的变量自动挂载到全局 window 对象上。这就是同一个 min.js 文件在普通网页环境下可正常运行、迁移到 Rails 后却报变量未定义的根本原因。

正确导入步骤 #

方案1：使用本地存储的 min.js 文件 #

• 调整文件存放位置：将原本放在 app/javascript/packs 目录下的 face-api.min.js，移动到 app/javascript/ 根目录下，不要放置在 packs 入口目录中，避免被 Webpack 识别为独立入口，造成重复打包或模块隔离问题。
• 在应用入口 JS（默认路径为 app/javascript/packs/application.js）中添加导入和全局暴露逻辑：

  // 导入本地存储的face-api模块
  import faceApi from '../face-api.min.js'
  // 手动将faceapi挂载到全局window对象，和纯HTML环境的脚本行为保持一致
  window.faceapi = faceApi
  

• 确认页面模板中通过 javascript_pack_tag 引入打包后的入口 JS，不要混用旧版 Sprockets 的 javascript_include_tag 单独引入静态文件，避免出现加载顺序混乱的问题。

方案2：更规范的 npm 包引入方式（推荐） #

这种方式不需要手动存放本地 min.js 文件，版本管理更稳定，升级也更方便：

• 在项目根目录执行依赖安装命令：

  yarn add face-api.js
  

• 在入口 JS 中引入并配置全局暴露：

  import * as faceapi from 'face-api.js'
  window.faceapi = faceapi
  

常见踩坑提醒 #

• 别把 face-api.min.js 扔到旧的 Sprockets 目录 app/assets/javascript 里，仅靠传统的 javascript_include_tag 加载。Rails 6 环境下，Webpack 打包的模块和 Sprockets 管理的静态文件作用域是相互隔离的，就算文件加载成功，跨作用域的变量也无法互相访问。
• 一定要保证 face-api 的导入、全局挂载逻辑，在所有依赖 faceapi 的业务逻辑代码之前执行，避免因为加载顺序问题触发未定义报错。
• 没必要额外修改 Webpack 的 ProvidePlugin 配置，手动把 faceapi 挂到 window 的方式，已经完全能匹配原来纯 HTML 环境下的调用逻辑，也不需要改动现有业务代码。

内容的提问来源于stack exchange，提问作者Chua