compass-html5-boilerplate 完全入门指南：Compass 版 HTML5 Boilerplate 究竟能帮你做什么？
项目地址: https://gitcode.com/gh_mirrors/co/compass-html5-boilerplate compass-html5-boilerplate 是 HTML5 Boilerplate 项目的 Compass 扩展版（由 Paul Irish 原作、Peter Gumeson 维护），它把 H5BP 的整套最佳实践封装成一个可复用的 Compass 库，让你用一条 compass create 命令就能快速搭建出完全符合规范的 HTML5 项目骨架。无论你是想生成独立 HTML5 项目，还是在 Rails 里集成 Haml + Sass/SCSS 模板，这份入门指南都能帮你快速上手。
compass-html5-boilerplate 是什么？为什么值得用？
HTML5 Boilerplate 本身是一个久经考验的前端"起步模板"，集成了标准化的 HTML 结构、跨浏览器样式、响应式媒体查询、404 页面、robots.txt、favicon 等一大堆细节。而 compass-html5-boilerplate 的核心价值在于：
- 🧩 模块化 Compass 库：H5BP 的样式被拆成一个个独立的 mixin，你可以按需挑选，而不是整包照搬
- 📁 自动生成项目骨架：一条命令生成完整的目录结构和配置文件
- 🎨 Sass/SCSS partials 管理：自动生成分层清晰的样式文件，方便维护
- 🏗️ Rails 友好：为 Rails 应用生成模块化的 Haml 布局（header、footer、flashes 等）
它依赖 compass 和 compass-h5bp 两个 gem，注册入口在 lib/html5-boilerplate.rb，本质上就是一个标准的 Compass Framework 扩展。
3 步完成安装：最快配置方法
对于独立项目（Standalone）场景，安装和初始化只需要两条命令：
gem install html5-boilerplate
compass create my_project -r compass-h5bp -r html5-boilerplate -u html5-boilerplate --javascripts-dir js --css-dir css
这里的 --javascripts-dir js --css-dir css 是为了和原版 H5BP 的目录结构保持一致；如果省略，记得修改 index.html.haml 里的 JS 和 CSS 引用路径。初始化完成后，在项目目录运行：
compass watch my_project
之后每次修改 SCSS，都会自动编译出 css/style.css，无需手动干预。
一条命令生成了什么？项目文件全景
执行 compass create 后，你会得到一个结构完整、开箱即用的项目，文件分发规则定义在 manifest.rb 中：
| 类别 | 生成文件 | 说明 |
|---|---|---|
| HTML 页面 | index.html、404.html | 主页骨架与友好 404 页 |
| 站点配置 | robots.txt、humans.txt、crossdomain.xml、.htaccess | 搜索引擎、作者信息、跨域与服务器配置 |
| 图标 | favicon.ico、apple-touch-icon*.png | 站点图标与移动端图标 |
| 样式 | style.scss + partials/_base.scss 等 | 分层 SCSS 源文件 |
| 脚本 | jquery、modernizr、plugins.js、script.js | 基础 JS 库与占位文件 |
其中 favicon 与 apple-touch-icon 文件分别来自 files/favicon.ico 和 files/apple-touch-icon.png 等模板资源。
样式分层设计：模块化 Compass 库的妙处
这是本扩展最值得玩味的地方。生成的主样式入口 style.scss 展示了清晰的分层思路：
- 先引入 partials/_base.scss 定义默认常量（字体颜色、链接颜色、行高、选中背景色等变量，均带
!default便于覆盖） - 再引入
h5bpCompass 扩展，一行@include h5bp-normalize;即可套用整套 normalize 样式 - 接着按需引入
partials/fonts、partials/page写自己的页面样式 - 最后引入 helpers 工具类和媒体查询
如果你想要更精细的控制，可以把 h5bp-normalize 换成对 partials/_overrides.scss 的引用——它会以独立 mixin 的形式逐项引入 display、base、selection、links、typography、lists、embeds、forms、tables 等模块，让你像搭积木一样只取自己需要的部分。
而 partials/_media.scss 则预置了 480px、768px 两个断点的媒体查询占位，以及内联打印样式 @include h5bp-media-print;，方便你快速写响应式布局。
Rails 项目：HAML 布局模板一键生成
如果你是 Rails 开发者，这个扩展同样贴心。当 Compass.configuration.project_type == :rails 时，manifest 会自动把整套 Haml 布局写入 app/views/layouts/：
- application.html.haml — 主布局，用
ie_html辅助方法生成 IE 条件注释 _head.html.haml、_header.html.haml、_footer.html.haml— 页面区块_flashes.html.haml、_stylesheets.html.haml、_javascripts.html.haml— 功能片段
辅助方法的实现集中在 lib/app/helpers/html5_boilerplate_helper.rb：ie_tag 会为 IE6/7/8 分别输出带 ie6、ie7、ie8 class 的条件注释，google_account_id 和 google_api_key 则支持从环境变量或 config/google.yml 读取配置，方便处理 Google Analytics 与 API 密钥。
Rails 下的安装同样简单：
gem install html5-boilerplate
cd my_rails_project
compass init rails -r html5-boilerplate -u html5-boilerplate --force
常见问题与避坑建议
Q1：版本怎么选？ 当前版本为 2.1.0（见 VERSION）。注意：新版的 compass-h5bp 已改用 normalize.css 而非 reset，与新版 H5BP 保持一致；如果你不打算升级，可以停留在 2.0.x。
Q2：Rails 用户是否应该用这个 gem？ 项目作者已经明确建议 Rails 新项目改用官方推荐的 html5-rails（基于 Rails 3 asset pipeline）。本 gem 更适合独立项目或旧版 Rails 场景。
Q3：生成目录不是预期的结构？ 检查 compass create 时是否遗漏了 --javascripts-dir、--css-dir 参数，并确认 manifest.rb 中的分发规则符合你的需求。
小结：它能帮你少写多少样板代码？
一句话总结：compass-html5-boilerplate 把 HTML5 Boilerplate 的工程化经验打包成了 Compass 生态里的一键生成器。它替你搞定了站点配置、图标、404 页面、跨浏览器样式和响应式骨架，还保留了充分的定制空间——这正是它至今仍有学习价值的原因。想动手体验，直接 clone 仓库源码研究吧：
git clone https://gitcode.com/gh_mirrors/co/compass-html5-boilerplate
从 manifest.rb 开始读，你很快就能理解一个 Compass 扩展的完整工作方式。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
