Rails应用中Stripe Checkout渲染与Stimulus控制器连接故障求助

问题现象 #

• Stripe Checkout组件无法渲染，客户端控制台无任何相关日志输出
• Stimulus控制器未正常连接，控制器内所有console.log语句均无输出

相关代码 #

stripe_controller.js #

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { publicKey: String, clientSecret: String }
  stripe = Stripe(this.publicKeyValue, { betas: ["embedded_checkout_beta_1"] });

  connect() {
    console.log("Stimulus controller connected");
  }

  async connect() {
    console.log("Connect method is called");
    console.log("Public Key:", this.publicKeyValue);
    console.log("Client Secret:", this.clientSecretValue);

    this.checkout = await this.stripe.initEmbeddedCheckout({
      clientSecret: this.clientSecretValue
    });

    console.log("Checkout Object:", this.checkout);

    this.checkout.mount(this.element);
  }

  disconnect() {
    this.checkout.destroy();
  }
}

importmap.rb #

# Pin npm packages by running ./bin/importmap

pin "application", preload: true
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
pin_all_from "app/javascript/controllers", under: "controllers"

show.html.erb #

<h1>Checkout Page</h1>
<%# <script type="module" src="/javascript/controllers/stripe_controller.js"></script> %>
<div data-controller="stripe"
  data-stripe-public-key-value="<%= Rails.application.credentials.dig(:stripe, :publishable_key)%>"
  data-stripe-client-secret-value="<%= @session.client_secret %>">
</div>

已采取排查步骤 #

• 核对importmap配置路径，确认无误
• 修改importmap后执行了资源预编译
• 将javascript_importmap_tags放置在布局文件的<head>标签内

更新信息 #

在application.js中添加console.log语句，页面加载后控制台无任何输出。

报错信息 #

浏览器控制台输出以下错误：

Uncaught TypeError: Failed to resolve module specifier "application". Relative references must start with either "/", "./", or "../".
Uncaught TypeError: Failed to resolve module specifier "@hotwired/turbo-rails". Relative references must start with either "/", "./", or "../".

版本信息 #

• Rails版本：7.0.8
• Turbo版本：@hotwired/turbo-rails: 8.0.0-beta.2

原因分析 #

1. 模块解析失败核心问题：浏览器无法识别application、@hotwired/turbo-rails这些模块别名，说明Importmap的映射规则没有被正确注入到页面中，导致模块加载流程中断。
2. Turbo版本兼容性冲突：Turbo 8.0.0-beta.2是为Rails 7.1及以上版本开发的，与Rails 7.0.8存在兼容性问题，会破坏Importmap的正常加载逻辑。
3. Stimulus控制器代码错误：控制器中重复定义了connect方法，后定义的方法会覆盖前一个，导致初始的连接日志无法输出；同时在类属性中直接使用this.publicKeyValue，此时控制器尚未完成初始化，会引发潜在错误。

解决建议 #

1. 修复Turbo版本兼容性 #

将Turbo降级到与Rails 7.0.x兼容的稳定版，执行命令：

./bin/importmap pin @hotwired/turbo-rails@7.3.0

执行完成后重启Rails服务器。

2. 确认Importmap正确注入 #

检查布局文件（如app/views/layouts/application.html.erb），确保javascript_importmap_tags标签存在且未被注释，放置在<head>内：

<head>
  <!-- 其他页面头部内容 -->
  <%= javascript_importmap_tags %>
</head>

3. 修复Stimulus控制器代码 #

删除重复的connect方法，调整Stripe实例初始化时机，添加错误捕获：

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { publicKey: String, clientSecret: String }
  stripe = null;
  checkout = null;

  connect() {
    console.log("Stimulus controller connected");
    console.log("Public Key:", this.publicKeyValue);
    console.log("Client Secret:", this.clientSecretValue);

    // 在控制器初始化完成后创建Stripe实例
    this.stripe = Stripe(this.publicKeyValue, { betas: ["embedded_checkout_beta_1"] });
    
    // 异步初始化Checkout
    this.initCheckout();
  }

  async initCheckout() {
    try {
      this.checkout = await this.stripe.initEmbeddedCheckout({
        clientSecret: this.clientSecretValue
      });
      console.log("Checkout Object:", this.checkout);
      this.checkout.mount(this.element);
    } catch (error) {
      console.error("初始化Stripe Checkout失败:", error);
    }
  }

  disconnect() {
    // 避免null调用destroy方法
    if (this.checkout) {
      this.checkout.destroy();
    }
  }
}

4. 验证application.js结构 #

确保app/javascript/application.js包含正确的导入语句，并添加测试日志：

console.log("Application JS已加载");
import "@hotwired/turbo-rails"
import "controllers"

5. 清除缓存并重启服务器 #

执行以下命令清除缓存，避免旧资源干扰：

rails tmp:clear

重启Rails服务器后刷新页面，查看控制台是否有日志输出，检查Stripe Checkout是否正常渲染。

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