在 ServBay 環境中安裝與設定 Sculpin

概述

Sculpin 是一款強大且靈活的基於 PHP 的靜態網站產生器，非常適合用於建立部落格、文件網站，或任何需要將動態內容（如 Twig 模板與 Markdown 檔案）轉為高效率靜態 HTML 頁面的專案。它利用 Composer 來管理相依性，並採用 Symfony 元件打造，為開發者帶來熟悉又可靠的開發體驗。

ServBay 是專為 macOS 設計的本地 Web 開發環境，整合了 PHP、Composer、資料庫（MySQL, PostgreSQL, MongoDB, Redis）、Web 伺服器（Caddy, Nginx）等多項常用套件，同時提供方便的圖形化介面管理。在 macOS 平台上使用 ServBay 能大幅簡化 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 Blog 樣板及所有相依並安裝於目前目錄（.）。

步驟 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 網域配置本機 DNS 及 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），通常免重新啟動服務。

步驟 4：產生 Sculpin 網站

網站設定完成後，接下來需讓 Sculpin 生成網站的靜態檔案。

於終端機中，確保您仍在 /Applications/ServBay/www/servbay-sculpin-app 專案根目錄下，執行以下指令安裝專案相依（如果第二步已執行過，此步驟可略，但建議再次執行以確認相依完整）：

composer install

再來，運行 Sculpin 產生命令：

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin：Composer 安裝的 Sculpin 執行檔路徑。
• generate：產生靜態網站指令。會根據 source 目錄內容與模板產生靜態檔案至 output 目錄（預設為 output_dev）。
• --watch：此旗標讓 Sculpin 偵測 source 目錄的檔案異動，有異動即自動重新產生，極為便利於開發流程中。

指令執行並出現 "Sculpin has generated your site!" 或類似訊息後，靜態內容已產生並存於 output_dev。

步驟 5：存取本地開發網站

此時即可透過 ServBay 設定的網域名稱瀏覽您的 Sculpin 網站。

開啟瀏覽器，訪問您第三步設定的網址：

https://servbay-sculpin.local

由於將網站根目錄指向 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（若採用美化網址設定）。您可透過 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 憑證，但您的 macOS 可能需信任 ServBay User CA。具體流程請參考 ServBay 官方文件。

常見問題集 (FAQ)

Q: 我修改檔案，但網站沒更新？

A: 請確認已於專案資料夾中執行 vendor/bin/sculpin generate --watch，並確定指令未因錯誤停止。檢查終端機輸出有無錯誤，也可嘗試清除瀏覽器快取或使用無痕視窗。

Q: 開啟 https://servbay-sculpin.local 出現 SSL 錯誤？

A: 這是因為 ServBay 為 .local 網域自動產生的憑證屬自簽名，須讓 macOS 信任 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 實用性，讓您專注於創作優質內容，而無需再因複雜的本機環境設定而煩惱。