Rails7中Stimulus控制器导入chart.js失败的原因与解决方法

我正在开发一个使用npm引入chart.js库的Rails 7应用。当在Stimulus控制器中添加代码import Chart from "chart.js/auto"后，浏览器日志出现报错：

Failed to register controller: hello (controllers/hello_controller) TypeError: The specifier “chart.js/auto” was a bare specifier, but was not remapped to anything. Relative module specifiers must start with “./”, “../” or “/”。

以下是复现错误的步骤：

1. 版本信息：

> ruby -v
ruby 3.1.0p0 (2021-12-25 revision fb4df44d16) [x86_64-linux]
> rails -v
Rails 7.1.3.4

2. 创建Rails应用：

> rails new example --css=bootstrap
> cd example
> rails g controller test index

3. 编写视图文件（app/views/test/index.html.erb）：

<h1>Test#index</h1>
<p>Find me in app/views/test/index.html.erb</p>

<div data-controller="hello"></div>

4. 编写Stimulus控制器（app/javascript/controllers/hello_controller.js）：

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.textContent = "Hello World!"
 }
}

5. 运行应用：

> bin/dev

打开http://localhost:3000/test/index，应用正常运行，无报错。
6. 触发错误：

• 安装chart.js：

  > npm i chart.js
  

• 修改Stimulus控制器，导入chart.js：

  import { Controller } from "@hotwired/stimulus"
  import Chart from "chart.js/auto" // 新增该行
  
  export default class extends Controller {
    connect() {
      this.element.textContent = "Hello World!"
   }
  }
  

• 刷新页面或重启应用后，浏览器出现上述报错。

这个错误核心是Rails 7默认使用的ESBuild无法解析chart.js/auto这类裸模块标识符。

ESBuild处理模块导入时，对于不带相对路径（.//..///）的裸标识符，需要明确的映射规则来找到实际文件路径。chart.js/auto属于npm包的子路径导出，ESBuild默认无对应映射配置，导致无法定位模块位置，从而抛出错误。

方法1：使用完整相对路径导入 #

直接指向chart.js包中auto的具体文件，替换导入语句：

import Chart from "../node_modules/chart.js/auto/auto.js"

这种方式无需额外配置，直接让ESBuild找到目标文件。

方法2：配置ESBuild路径解析规则 #

在Rails的ESBuild配置中添加路径映射，让ESBuild识别chart.js/auto这类裸标识符：

1. 项目根目录创建esbuild.config.js文件：

const path = require('path');

module.exports = {
  resolve: {
    alias: {
      'chart.js/auto': path.resolve(__dirname, 'node_modules/chart.js/auto/auto.js')
    }
  }
};

2. 修改config/application.rb，指定ESBuild配置文件：

# config/application.rb
module Example
  class Application < Rails::Application
    # 其他配置...
    config.esbuild.config = Rails.root.join("esbuild.config.js")
  end
end

3. 重启bin/dev，此时import Chart from "chart.js/auto"即可正常解析。

方法3：改用Importmap（若项目使用Importmap） #

如果项目默认使用Importmap而非npm管理前端依赖，可通过以下步骤配置：

1. 运行命令添加chart.js的映射：

> bin/importmap pin chart.js

2. 在Stimulus控制器中直接导入：

import Chart from "chart.js/auto"

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