在 ServBay 环境中安装和配置 Jigsaw

概述

本文档旨在指导您如何在 ServBay 这一强大的本地 Web 开发环境中安装和配置 Jigsaw 静态网站生成器。ServBay 为 PHP、Node.js 等多种技术栈提供了集成的环境，极大地简化了 Jigsaw 项目的搭建过程。通过 ServBay，您可以轻松地为 Jigsaw 项目配置本地域名、HTTPS 以及高效的 Web 服务器，从而专注于网站内容的开发。

什么是 Jigsaw？

Jigsaw 是一个基于 Laravel 组件构建的静态网站生成器，由 Tighten 公司开发。它利用了 Laravel Blade 模板引擎的强大功能和灵活性，并结合 Markdown 文件来生成纯静态 HTML 网站。Jigsaw 非常适合用于构建文档站点、博客、营销页面或任何不需要后端数据库和动态服务器处理的网站。其核心优势在于：

• 利用熟悉的工具: 如果您熟悉 Laravel 或 Blade 模板，Jigsaw 将非常容易上手。
• 性能与安全: 生成的静态网站加载速度快，且由于没有服务器端代码执行，安全性更高。
• 灵活的模板: 使用 Blade 模板可以构建复杂的布局和组件。
• Markdown 支持: 轻松撰写内容。

应用场景

Jigsaw 适用于以下场景：

• 项目文档和 API 文档站点
• 个人博客或技术分享网站
• 企业或产品的营销着陆页
• 小型展示网站
• 任何对性能和安全性要求较高、内容相对固定的网站

前提条件

在开始之前，请确保您已满足以下条件：

1. ServBay 已安装并运行: 您需要在 macOS 系统上安装并启动 ServBay。ServBay 已经内置了 PHP、Composer 和 Node.js/npm，这是安装和运行 Jigsaw 所必需的。
2. 基本的命令行操作知识: 您需要使用终端执行一些命令。
3. 对 Composer 和 npm 有基本了解: Jigsaw 的安装依赖 Composer，前端资产的编译依赖 npm。

安装和配置步骤

本节将详细介绍在 ServBay 环境中安装和配置 Jigsaw 项目的具体步骤。

步骤 1: 创建项目目录

首先，打开您的终端应用，进入 ServBay 建议的网站根目录 /Applications/ServBay/www，并为您的 Jigsaw 项目创建一个新的子目录。

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

我们将项目目录命名为 servbay-jigsaw-demo，所有项目文件将存放在此。

步骤 2: 使用 Composer 创建 Jigsaw 项目

ServBay 已经预装并配置好了 Composer，您可以在任何终端窗口直接使用 composer 命令。现在，在您刚才创建的项目目录 (/Applications/ServBay/www/servbay-jigsaw-demo) 中运行 Composer 命令来创建 Jigsaw 项目：

composer create-project tightenco/jigsaw .

这个命令会下载 Jigsaw 的最新版本及其所有 PHP 依赖到当前目录 (.)。请注意末尾的 . 表示将项目创建在当前目录，而不是在当前目录下再创建一个名为 jigsaw 的子目录。

步骤 3: 配置 ServBay 网站

为了通过 Web 浏览器访问您的 Jigsaw 网站，您需要在 ServBay 中为此项目配置一个本地网站。

1. 打开 ServBay UI: 双击 ServBay 应用图标或通过菜单栏图标打开 ServBay 控制面板。
2. 导航到「网站」: 在左侧导航栏中，点击「网站」标签页。
3. 添加新网站: 点击界面底部的「+」按钮，选择「添加网站」。
4. 配置网站详情:
   • 名字 (Name)：输入一个易于识别的名称，例如 ServBay Jigsaw Demo。
   • 域名 (Domain)：输入您想用于本地访问的域名。建议使用 .servbay.demo 后缀以避免与真实域名冲突，例如 jigsaw-demo.servbay.demo。ServBay 会自动将 .servbay.demo 域名解析到本地。
   • 网站类型 (Site Type)：选择 PHP，因为 Jigsaw 的构建过程需要 PHP 环境。
   • PHP 版本 (PHP Version)：选择一个 ServBay 中已安装的 PHP 版本，推荐使用较新的稳定版本。
   • 网站根目录 (Site Root)：这是非常关键的一步。Jigsaw 构建后生成的静态文件默认存放在项目根目录下的 build_local 目录中。因此，您需要将网站根目录指向这个构建输出目录： /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. 保存并应用: 填写完所有信息后，点击「保存」按钮。ServBay 会提示您应用更改，点击确认。ServBay 会自动更新 Web 服务器配置（Caddy 或 Nginx），并为您配置 HTTPS。

步骤 4: 安装前端依赖

Jigsaw 项目通常会使用 npm 来管理和编译前端资产（如 CSS 预处理器 SASS、JavaScript 文件等）。在 ServBay 环境中，Node.js 和 npm 也是内置可用的。

在您的项目目录 (/Applications/ServBay/www/servbay-jigsaw-demo) 中运行以下命令来安装前端依赖：

npm install

这将读取项目根目录下的 package.json 文件，并下载所需的 Node.js 模块到 node_modules 目录中。

步骤 5: 构建 Jigsaw 网站

安装完所有依赖后，您需要运行 Jigsaw 的构建命令来生成静态网站文件。

在项目目录中运行以下命令：

./vendor/bin/jigsaw build

这个命令会执行以下操作：

1. 处理 source 目录中的 Markdown 文件和 Blade 模板。
2. 运行 webpack.mix.js 中定义的编译任务（如果 npm install 包含了 Laravel Mix）。
3. 将最终生成的静态 HTML、CSS、JS 和其他资产输出到 build_local 目录。

步骤 6: 访问网站

现在，您的 Jigsaw 网站的静态文件已经生成并存放于 /Applications/ServBay/www/servbay-jigsaw-demo/build_local 目录中。由于您已经在 ServBay 中将网站根目录指向了这里，您现在可以通过浏览器访问之前配置的本地域名来查看网站。

打开您的 Web 浏览器，访问您在步骤 3 中配置的域名，例如 https://jigsaw-demo.servbay.demo。ServBay 会自动处理本地 HTTPS 证书（使用 ServBay User CA），您应该能看到 Jigsaw 默认的欢迎页面。

自定义和开发

现在您已经成功搭建了基础环境，可以开始自定义您的 Jigsaw 网站内容和样式了。

编辑内容和模板

• 网站的源代码位于项目根目录下的 source 目录。
• HTML 布局和组件使用 Blade 模板，存放在 source/_layouts 和 source/_partials 等子目录中。
• 页面内容通常使用 Markdown 编写，存放在 source 目录或其子目录中（例如 source/index.md, source/about.md）。
• 博客文章通常放在 source/_posts 目录，使用 YYYY-MM-DD-slug.md 的命名格式。

添加新页面/文章

要添加一个新页面或博客文章，只需在 source 目录或相应的子目录（如 source/_posts）中创建一个新的 Markdown 文件。

例如，创建一个 source/about.md 文件：

---
title: "关于我们"
description: "了解 ServBay Jigsaw Demo 的更多信息"
---

# 关于我们

这是一个使用 Jigsaw 构建的关于页面。

在这里您可以添加公司介绍、团队信息等内容。

自定义样式和脚本

Jigsaw 项目通常使用 Laravel Mix (webpack.mix.js) 来编译前端资产。

• 样式文件（通常是 SASS/SCSS）存放在 source/_assets/sass 目录。
• JavaScript 文件存放在 source/_assets/js 目录。

在项目目录中，您可以使用 npm 脚本来编译这些资产：

• npm run dev: 编译开发环境下的资产，通常包含 Source Maps，不压缩。
• npm run watch: 编译开发环境下的资产，并监听文件变化，自动重新编译。在开发过程中非常有用。
• npm run prod: 编译生产环境下的资产，通常进行压缩和优化。

例如，修改 source/_assets/sass/main.scss 后，运行 npm run dev 或 npm run watch 来编译生成对应的 CSS 文件。

重新构建网站

重要提示: 每次修改了 source 目录中的 内容文件 (Markdown) 或 模板文件 (Blade) 后，您都必须重新运行 Jigsaw 的构建命令，以便 Jigsaw 处理这些更改并更新 build_local 目录中的静态文件：

./vendor/bin/jigsaw build

如果您修改了 前端资产文件 (SASS, JS)，您需要运行 npm run dev 或 npm run watch 来重新编译这些资产。在大多数 Jigsaw 项目中，Jigsaw 的 build 命令也会触发 Mix 的编译过程，但分开理解有助于调试。

注意事项

• 构建输出目录: Jigsaw 默认构建到 build_local (开发环境) 和 build_production (生产环境)。请确保 ServBay 网站根目录指向了您希望访问的目录（通常本地开发指向 build_local）。
• Web 服务器: ServBay 使用 Caddy 或 Nginx 作为 Web 服务器，它们直接服务于 build_local 目录中的静态文件，效率很高。您不需要使用 Jigsaw 内置的 jigsaw serve 命令（它主要用于快速预览，功能不如 ServBay 的全功能 Web 服务器）。
• HTTPS: ServBay 会自动为 .servbay.demo 域名配置 HTTPS，并使用 ServBay User CA 签发证书。您可能需要在系统中信任 ServBay User CA 证书，以避免浏览器警告。
• 干净构建: 如果遇到奇怪的构建问题，可以尝试使用 ./vendor/bin/jigsaw build --clean 命令进行一次干净的构建。

常见问题 (FAQ)

Q: 我修改了 Markdown 文件，为什么在浏览器中看不到更新？

A: 您需要在修改内容或模板后，在终端中运行 ./vendor/bin/jigsaw build 命令来重新构建网站。

Q: 我修改了 SCSS 文件，为什么样式没有变化？

A: 您需要在修改前端资产后，在项目目录中运行 npm run dev 或 npm run watch 命令来重新编译前端资产。

Q: 访问本地域名时显示“无法访问”或“找不到文件”？

A: 请检查以下几点：

1. 确保 ServBay 正在运行。
2. 检查 ServBay 中该网站的配置：域名是否正确？网站根目录是否正确指向了 /Applications/ServBay/www/servbay-jigsaw-demo/build_local？
3. 确保您已经成功运行了 ./vendor/bin/jigsaw build 命令，并且 build_local 目录下确实生成了静态文件（例如 index.html）。

Q: 如何部署 Jigsaw 网站？

A: Jigsaw 生成的是纯静态文件。通常流程是：

1. 运行 ./vendor/bin/jigsaw build production 构建生产环境文件（通常会进行更多优化）。
2. 将 build_production 目录下的所有文件上传到任何支持静态网站托管的服务商（如 Netlify, Vercel, GitHub Pages, 各种云存储等）。

总结

通过 ServBay，在 macOS 环境下安装和配置 Jigsaw 静态网站生成器变得非常高效和便捷。ServBay 提供了所需的全部运行环境（PHP, Composer, Node.js, npm）以及强大的本地 Web 服务器配置能力。遵循本指南，您可以快速启动 Jigsaw 项目，并利用 ServBay 的各项功能来优化您的本地开发流程。