用Middleman构建静态站点的踩坑经验与优化技巧分享

我的写法，亲测靠谱

Middleman 用久了，我总结了一套比较顺手的开发模式。最核心的就是善用 helpers 和 partials，把代码拆得清清爽爽。

比如我在项目里经常会定义一个专门处理日期格式化的 helper：

module FormatHelper
  def format_date(date)
    date.strftime("%Y-%m-%d") if date
  end
end

这样在模板里直接调用 就能保证所有日期都统一格式。千万别在模板里直接写 ，分散在各处的日期格式化逻辑会让你改起来特别痛苦。

这几种错误写法，别再踩坑了

说真的，有些错误我年轻时犯过好几次。比如有人喜欢在 config.rb 里疯狂堆配置：

activate :asset_hash
activate :directory_indexes
activate :gzip
activate :minify_css
# 省略十几行...

看起来挺厉害的样子，但这种做法有几个大问题：首先是可读性差，维护成本高；其次是一旦项目需要定制某些功能，这种大杂烩式的配置会让你很难定位问题。

更糟糕的是，很多人直接 copy 别人的配置，结果引入一堆用不上的 gem，最后项目臃肿得不行。记得有个项目，光是启动就要等十几秒，排查后发现是加载了一堆无用的插件。

实际项目中的坑

在实际项目中，最容易出问题的就是数据源的处理。Middleman 支持多种数据源方式，但我强烈建议使用 YAML 或 JSON 文件来管理数据，而不是全部塞到 Frontmatter 里。

举个例子，我之前接手一个博客项目，每篇文章的元信息都写在 Markdown 的 Frontmatter 里：

---
title: "最佳实践"
date: 2023-10-01
tags:
  - 技术
  - 分享
---

看着挺方便，但当文章数量达到上百篇时，想修改某个标签或者整理分类就变得极其痛苦。后来我改成用单独的 data 文件管理：

posts.yml
post1:
  title: "最佳实践"
  date: 2023-10-01
  tags:
    - 技术
    - 分享

虽然多了一个文件，但管理起来清晰多了。而且可以很方便地做批量操作，比如我想统计所有包含”技术”标签的文章数：

data.posts.select { |_,v| v.tags.include?("技术") }.count

几个实用的小技巧

说几个我觉得特别实用的小技巧。首先是环境变量的使用，这个太重要了。比如不同环境下的 API 地址：

configure :development do
  set :api_url, "http://localhost:3000"
end

configure :build do
  set :api_url, "https://jztheme.com/api"
end

然后在模板里就可以这样用：

<script>

  const API_URL = "<%= api_url %>";

</script>

`&gt;

&lt;p&gt;另一个就是别忘了 Middleman 自带的 live reload 功能。很多人不知道这个特性，在开发时手动刷新页面累得半死。其实只要在 Gemfile 里加上：&lt;/p&gt;</code></pre>ruby

gem 'middleman-livereload'

<pre class="pure-highlightjs line-numbers language-none"><code class="no-highlight language-none">&lt;p&gt;然后在 config.rb 里启用：&lt;/p&gt;</code></pre>ruby

activate :livereload

<pre class="pure-highlightjs line-numbers language-none"><code class="no-highlight language-none">&lt;p&gt;就能享受自动刷新的便利了。&lt;/p&gt;

&lt;h2&gt;关于部署的一些心得&lt;/h2&gt;

&lt;p&gt;部署这块儿也踩过不少坑。最大的教训就是千万别直接把 build 出来的文件丢给运维就完事了。我现在的做法是：&lt;/p&gt;

&lt;ul&gt;

  &lt;li&gt;先用 middleman build 打包&lt;/li&gt;

  &lt;li&gt;写个简单的 deploy 脚本&lt;/li&gt;

  &lt;li&gt;在 CI/CD 里跑测试&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;分享一个简单的 deploy 脚本：&lt;/p&gt;</code></pre>bash

#!/bin/bash

set -e
echo "开始构建..."

bundle exec middleman build
echo "同步到服务器..."

rsync -avz --delete build/ user@server:/var/www/site/

``
记得加 set -e，这样任何一个命令失败都会终止脚本执行，避免把错误的文件部署上去。
以上是我总结的最佳实践
写到这里差不多该收尾了。这些经验都是我踩过无数坑后总结出来的，希望能帮到刚开始用 Middleman 的同学。当然，每个项目都有自己的特点，我的方案不一定适用于所有场景。
如果你有更好的实践经验，欢迎在评论区分享。或者你遇到了什么难题，也可以留言讨论。毕竟，写代码这事，谁还没踩过几个坑呢？