ServBay

简体中文

English
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

简体中文

English
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

Appearance

在 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 项目创建一个新的子目录。

bash
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 项目：

bash
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) 中运行以下命令来安装前端依赖：

bash
npm install

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

步骤 5: 构建 Jigsaw 网站 ​

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

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

bash
./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 文件：

markdown
---
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 目录中的静态文件：

bash
./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 的各项功能来优化您的本地开发流程。