如何在Rails 7项目中正确集成Materialize CSS

直接使用--css=materialize参数生成项目失败，核心原因是默认生成的配置未适配Rails 7的资产编译规则，缺失JS组件初始化逻辑，会出现样式丢失、组件无响应、M is not defined控制台报错等问题，按以下步骤操作即可正常使用。

方案一：无Node依赖（Importmap + Sprockets，推荐大多数场景使用） #

• 新建项目时不要加--css=materialize参数，直接用默认命令创建：

  rails new 你的项目名
  

• 如果是之前配置失败的现有项目，先清理残留依赖：删除Gemfile中所有materialize相关的gem，删除app/assets/stylesheets目录下所有带materialize字样的样式文件，删除importmap.rb、application.js中之前添加的materialize相关引入，执行bundle install更新依赖。
• 在Gemfile中添加稳定版Materialize的sass依赖：

  gem 'materialize-sass', '~> 1.0.0'
  

  执行bundle install完成安装。
• 将app/assets/stylesheets/application.css重命名为application.scss，删除文件内原有的*= require_self、*= require_tree .等sprockets指令注释，添加样式引入：

  @import "materialize";
  

• 打开config/importmap.rb，添加JS依赖映射：

  pin "materialize", to: "materialize.js"
  

• 打开app/javascript/application.js，添加JS引入和全局初始化代码：

  import "materialize"
  
  document.addEventListener("DOMContentLoaded", () => {
    M.AutoInit()
  })
  

• 打开布局文件app/views/layouts/application.html.erb，在head标签内添加Material Icons字体引入，不使用CDN的话可以自行下载图标文件放到本地资产目录引用：

  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
  

• 执行rails assets:clobber清除旧的编译缓存，重启Rails服务，浏览器端硬刷新（Ctrl+Shift+R / Cmd+Shift+R）清缓存即可。

方案二：Node构建模式（jsbundling + cssbundling，适合需要自定义编译配置的场景） #

• 先安装sass构建依赖：

  rails css:install:sass
  

• 用包管理器安装Materialize依赖：

  yarn add materialize-css@1.0.0
  # 用npm的话执行 npm install materialize-css@1.0.0
  

• 打开app/assets/builds/application.scss，添加样式引入：

  @import "materialize-css/dist/css/materialize.min.css";
  

• 打开app/javascript/application.js，添加JS引入和初始化：

  import M from "materialize-css"
  
  document.addEventListener("DOMContentLoaded", () => {
    M.AutoInit()
  })
  

• 同方案一，在布局文件中添加Material Icons字体引入，清除缓存重启服务即可。

常见避坑提示 #

不要同时在Gemfile安装materialize-sass、又在yarn/npm中安装materialize-css，重复引入会导致样式冲突、组件重复初始化报错。
所有配置修改后必须执行资产清理命令，否则旧的编译缓存会导致配置不生效。
如果出现下拉框、模态框、轮播等JS组件无响应的问题，优先检查控制台是否有M is not defined报错，确认JS引入顺序在初始化代码之前。

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