在 ServBay 环境中安装和配置 Sculpin

概述

Sculpin 是一个强大且灵活的基于 PHP 的静态网站生成器，特别适合用于构建博客、文档网站或任何需要将动态内容（如 Twig 模板和 Markdown 文件）转换为高性能静态 HTML 页面的项目。它利用 Composer 管理依赖，并采用 Symfony 组件构建，为开发者提供了熟悉且可靠的开发体验。

ServBay 是一款专为 macOS 设计的本地 Web 开发环境，集成了多种常用的软件包，包括 PHP、Composer、数据库（MySQL, PostgreSQL, MongoDB, Redis）、Web 服务器（Caddy, Nginx）等，并提供便捷的图形界面管理。使用 ServBay 可以极大地简化在 macOS 上搭建 Sculpin 开发环境的过程，特别是处理 PHP 版本、依赖管理和 Web 服务器配置。

本指南将详细介绍如何在 ServBay 环境中安装和配置 Sculpin，并设置一个本地开发网站。

应用场景

• 使用 PHP 技术栈构建高性能的静态博客。
• 为开源项目或产品生成静态文档网站。
• 快速搭建不需要后端数据库的静态营销页面或企业网站。
• 利用 Twig 模板引擎和 Markdown 编写内容，享受静态网站的速度和安全性。

前提条件

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

1. 已在 macOS 系统上安装并运行 ServBay。ServBay 提供了所需的 PHP 环境、Composer 依赖管理器以及 Web 服务器（Caddy 或 Nginx）。
2. 具备基本的命令行操作知识。
3. 了解 PHP、Composer 和 Markdown 的基本概念。

安装 Sculpin 的步骤

以下是在 ServBay 环境中安装和配置 Sculpin 的详细步骤：

步骤 1：创建项目目录

首先，在 ServBay 的网站根目录 (/Applications/ServBay/www) 中创建一个新的项目目录。我们将使用 servbay-sculpin-app 作为示例项目名称。

打开终端并执行以下命令：

cd /Applications/ServBay/www
mkdir servbay-sculpin-app
cd servbay-sculpin-app

这个目录将存放您的 Sculpin 项目文件。

步骤 2：使用 Composer 创建 Sculpin 项目

ServBay 已经自带 Composer，无需额外安装。您可以在终端中直接使用 composer 命令。

我们将使用 Sculpin 官方提供的博客骨架项目来快速启动。在您刚刚创建的 servbay-sculpin-app 目录中，运行以下 Composer 命令：

composer create-project sculpin/sculpin-blog-skeleton .

此命令会通过 Composer 下载 Sculpin 博客骨架项目及其所有依赖，并将其安装到当前目录 (.) 中。

步骤 3：配置 ServBay 网站

为了通过 ServBay 的 Web 服务器（Caddy 或 Nginx）访问您的 Sculpin 网站，您需要在 ServBay 中添加一个网站配置。

1. 打开 ServBay 应用：启动 ServBay 图形界面。
2. 前往「网站」标签：在 ServBay 窗口中，点击导航栏中的「网站」标签页。
3. 添加新网站：点击左下角的「+」按钮，添加一个新的网站配置。
4. 填写网站信息：
   • 名字 (Name)：输入一个易于识别的名称，例如 My Sculpin Site。
   • 域名 (Domain)：输入您希望在本地访问网站的域名，例如 servbay-sculpin.local。ServBay 会自动为 .local 域名配置本地解析和 SSL 证书（使用 ServBay User CA）。
   • 网站类型 (Type)：选择 PHP，因为 Sculpin 是一个 PHP 应用。
   • PHP 版本 (PHP Version)：选择一个您希望使用的 PHP 版本。ServBay 支持多版本 PHP，请选择一个与 Sculpin 兼容的版本（通常较新版本即可）。
   • 网站根目录 (Document Root)：这是关键一步。Sculpin 生成的静态文件默认存放在项目目录下的 output_dev 或 output_prod 目录中。对于本地开发，我们将网站根目录指向开发输出目录： /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. 保存配置：填写完毕后，点击「保存」按钮。ServBay 会自动应用新的配置到其 Web 服务器（Caddy 或 Nginx）。通常无需手动重启 ServBay 服务。

步骤 4：构建 Sculpin 网站

在 ServBay 配置好网站后，您需要让 Sculpin 生成网站的静态文件。

在终端中，确保您仍在项目的根目录 /Applications/ServBay/www/servbay-sculpin-app 中，然后运行以下命令来安装项目依赖（如果步骤 2 已经执行，此步可能不是必须的，但执行一次可以确保所有依赖都已正确安装）：

composer install

接下来，运行 Sculpin 的生成命令来构建网站：

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin：这是通过 Composer 安装的 Sculpin 可执行文件的路径。
• generate：这是 Sculpin 用于生成静态网站的命令。它会读取 source 目录中的内容和模板，然后将生成的静态文件输出到配置的输出目录（默认为 output_dev）。
• --watch：这个标志告诉 Sculpin 监听 source 目录中的文件变化。当文件发生改变时，Sculpin 会自动重新生成网站，这在开发过程中非常方便。

当命令执行并显示 "Sculpin has generated your site!" 或类似信息后，静态文件就已经生成并存放在 output_dev 目录中了。

步骤 5：访问本地开发网站

现在，您可以通过 ServBay 配置的域名访问您的 Sculpin 网站了。

打开您的 Web 浏览器，访问您在步骤 3 中配置的域名：

https://servbay-sculpin.local

由于您将 ServBay 网站的根目录指向了 output_dev，并且 sculpin generate --watch 命令正在运行并监听文件变化，您现在可以通过 https://servbay-sculpin.local 实时预览您对网站内容和模板的修改。ServBay 提供的自动 SSL 证书确保您可以通过 HTTPS 安全地访问本地网站。

使用 Sculpin 进行开发

现在您已经在 ServBay 环境中成功安装和配置了 Sculpin，可以开始构建您的静态网站了。以下是一些基础开发操作：

Sculpin 项目结构简介

了解 Sculpin 的基本项目结构有助于您进行开发：

servbay-sculpin-app/
├── app/                # 应用配置和缓存
├── output_dev/         # 开发环境生成的静态文件输出目录 (ServBay 网站根目录指向这里)
├── output_prod/        # 生产环境生成的静态文件输出目录
├── source/             # 网站的源文件（Markdown 内容、Twig 模板、静态资源等）
│   ├── _layouts/       # Twig 布局文件
│   ├── _posts/         # 博客文章 Markdown 文件
│   ├── assets/         # 静态资源（CSS, JS, 图片等）
│   └── index.md        # 首页 Markdown 文件
├── vendor/             # Composer 安装的依赖库
├── sculpin.yml         # Sculpin 主配置文件
├── composer.json       # Composer 依赖配置文件
└── ...其他文件

您的主要工作将在 source 目录中进行。

创建博客文章

要在您的 Sculpin 博客中创建一篇新文章，只需在 source/_posts 目录中创建一个新的 Markdown 文件。文件命名通常遵循 YYYY-MM-DD-slug.md 的格式。

例如，创建一个 2024-06-06-my-first-post.md 文件：

---
title: "我的第一篇文章"
date: 2024-06-06
tags: [教程, Sculpin, ServBay]
---

# 我的第一篇文章

这是我的第一篇 Sculpin 博客文章的内容。我在这里分享一些关于 ServBay 和 Sculpin 的使用经验。

您可以在这里使用 Markdown 语法编写内容。

## 小标题

列表：
- 项目 1
- 项目 2

保存文件后，由于您正在运行 sculpin generate --watch 命令，Sculpin 会自动检测到文件变化并重新生成网站。刷新浏览器中的 https://servbay-sculpin.local 即可看到新文章。

创建新页面

要添加一个独立页面（例如“关于我们”页面），在 source 目录中直接创建一个 Markdown 文件，例如 about.md：

---
title: "关于我们"
layout: page.html.twig # 指定使用的布局文件
---

# 关于 ServBay Sculpin 指南

这个页面是关于使用 ServBay 和 Sculpin 构建静态网站的指南。

保存文件后，Sculpin 会生成 output_dev/about/index.html 文件（如果配置了漂亮的 URL）。您可以通过 https://servbay-sculpin.local/about/ 访问这个页面。

自定义样式和脚本

静态资源（如 CSS 和 JavaScript 文件）通常存放在 source/assets 目录中。您可以直接编辑这些文件。

例如，编辑 source/assets/css/style.css 文件来修改网站样式。

这些资源在网站生成时会被复制到输出目录。如果您修改了这些文件，Sculpin 的 --watch 功能也会检测到并触发重新生成。

构建用于生产环境的网站

当您的网站开发完成后，您需要构建一个用于部署到生产环境的版本。生产环境的构建通常会进行一些优化，例如资源压缩等。

使用以下命令构建生产环境版本：

vendor/bin/sculpin generate --env=prod

此命令会将生成的静态文件输出到 output_prod 目录。您可以将 output_prod 目录中的所有文件上传到任何静态网站托管服务（如 GitHub Pages, Netlify, Vercel, 或者您自己的 Web 服务器）进行部署。

如果您想通过 ServBay 查看生产环境的构建结果，可以修改 ServBay 网站配置的「网站根目录」指向 /Applications/ServBay/www/servbay-sculpin-app/output_prod，然后保存配置并访问域名。

注意事项

• 确保 ServBay 正在运行，并且您配置的网站已启用。
• 确认 sculpin generate --watch 命令正在终端中运行，以便在开发过程中自动更新网站。
• 检查 ServBay 网站配置中的「网站根目录」是否正确指向了 Sculpin 的输出目录（开发时通常是 output_dev）。
• ServBay 自动为 .local 域名提供了 SSL 证书，但您的操作系统可能需要信任 ServBay User CA。具体步骤请参考 ServBay 的文档。

常见问题解答 (FAQ)

Q: 我修改了文件，但网站没有更新？

A: 确保您在项目目录中运行了 vendor/bin/sculpin generate --watch 命令，并且该命令没有因错误而中断。检查终端输出是否有错误信息。同时，清除浏览器缓存或使用隐私模式访问。

Q: 访问 https://servbay-sculpin.local 时显示 SSL 错误？

A: 这是因为 ServBay 为 .local 域名生成的是自签名证书，需要您的操作系统信任 ServBay User CA。请按照 ServBay 文档中的指引安装并信任 CA 证书。

Q: 如何更改 PHP 版本？

A: 您可以在 ServBay 应用的「软件包」标签页中安装和管理不同的 PHP 版本。然后在「网站」标签页中编辑您的 Sculpin 网站配置，选择所需的 PHP 版本并保存。

Q: Sculpin 支持哪些模板引擎和标记语言？

A: Sculpin 默认使用 Twig 作为模板引擎，并广泛支持 Markdown 用于内容编写。

总结

通过 ServBay 提供的集成环境，在 macOS 上安装和配置 Sculpin 静态网站生成器变得非常便捷。ServBay 预装的 PHP 和 Composer，以及易于配置的 Web 服务器和自动 SSL 功能，为 Sculpin 的本地开发提供了坚实的基础。遵循本指南，您可以快速搭建 Sculpin 开发环境，并高效地构建和预览您的静态网站项目。利用 Sculpin 的强大功能结合 ServBay 的便利性，您可以专注于创造优质内容，而无需花费大量时间配置复杂的本地开发环境。