在 ServBay 環境中安裝與設定 Kirby CMS

Kirby 是一套靈活且強大的檔案導向內容管理系統（CMS），非常適合用來建置各類型網站。與傳統以資料庫為基礎的 CMS 不同，Kirby 直接將內容儲存在檔案系統中，因此相當輕量、易於版本控制並且部署便利。

本教學將引導您如何在專為開發者打造的本機 Web 開發環境——ServBay 中，透過 Composer 安裝並設定 Kirby 4.2 Starterkit。ServBay 已預先配置 PHP、Web 伺服器（如 Caddy 或 Nginx）和 Composer，是本機開發 Kirby 專案的理想平台。

前置條件

在開始之前，請確認您已完成以下事項：

1. 已於 macOS 上安裝並執行 ServBay。
2. 已於 ServBay 中啟用所需 PHP 版本（本例以 PHP 8.2 為例）。
3. ServBay 已內建 Composer，無需額外安裝。

Kirby 安裝步驟

以下是在 ServBay 環境中安裝與配置 Kirby 的完整步驟：

步驟 1：建立專案目錄

首先，開啟終端機程式。前往 ServBay 預設的網站根目錄 /Applications/ServBay/www，並建立一個新的專案目錄。本範例將使用 servbay-kirby-app 作為專案名稱。

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

步驟 2：使用 Composer 建立 Kirby 專案

ServBay 已整合 Composer，您可以直接在終端機中使用。在 servbay-kirby-app 專案目錄下，執行下列 Composer 指令下載並建立 Kirby Starterkit：

composer create-project getkirby/starterkit .

此指令會將 Kirby 核心檔案、相依套件及一套包含基礎內容與範本的 Starterkit 下載至目前目錄（.）。

步驟 3：網站伺服器設定（於 ServBay 新增網站）

為使 ServBay 的 Web 伺服器（Caddy 或 Nginx 等）能服務您的 Kirby 專案，需在 ServBay 應用中新增一組網站設定。

1. 開啟 ServBay 應用程式：啟動 ServBay。
2. 進入網站管理：點選 ServBay 視窗左側導覽欄的「網站」分頁。
3. 新增網站：點擊畫面下方的「+」按鈕或類似新增網站的選項。
4. 填寫網站資訊：於跳出的設定視窗中輸入下列資訊：
   • 名稱：為您的網站命名（易辨識即可），例如 My Kirby Site。
   • 網域：設定本機開發網域，建議使用 .local 或 .servbay.demo 結尾，例如 servbay-kirby.local。ServBay 會自動為您設定本機 DNS 解析。
   • 網站類型：選擇 PHP，因 Kirby 屬於 PHP 應用。
   • PHP 版本：選擇希望使用的 PHP 版本，如 8.2。請確認此版本符合 Kirby 最低需求。
   • 網站根目錄：指定 Kirby 專案的 index.php 所在目錄。就 Starterkit 而言，通常即為專案根目錄。請輸入或透過檔案選擇視窗，選擇於步驟 1 建立的目錄路徑：/Applications/ServBay/www/servbay-kirby-app。
5. 儲存設定：確認上述資訊無誤後，點擊儲存。ServBay 會自動套用新設定，並可能需重啟相關 Web 伺服器。

步驟 4：Kirby 基礎設定

Kirby 主要透過 site/config/config.php 檔進行核心設定。對於 Starterkit 來說，預設配置已足夠直接運作，您可於此檔案中加入自訂設定，例如：

• 啟用偵錯模式（c::set('debug', true);）
• 設定面板語言
• 自訂路由規則等

您專案根目錄下的 content 資料夾會由 Starterkit 自動建立，專門用來存放網站所有頁面內容。

步驟 5：執行與存取您的 Kirby 網站

完成 ServBay 設定後，您即可用先前設定的網域方式存取您的 Kirby 網站。

1. 確認 ServBay 正常運作：保證 ServBay 正在執行，且相關 Web 伺服器（Caddy 或 Nginx）與 PHP 套件皆已啟動。
2. 網站瀏覽：開啟您的網頁瀏覽器，於網址列輸入您於步驟 3 設定的網域名稱，例如 https://servbay-kirby.local。

您應該會看到 Kirby Starterkit 的預設歡迎頁。ServBay 預設啟用 HTTPS，故建議以 https:// 存取。

步驟 6：安裝並使用 Kirby 面板（選用）

Kirby 提供強大的管理面板，方便網站內容、使用者與相關設定管理。

1. 進入面板安裝頁：於瀏覽器輸入您的網站網域，並加上 /panel 路徑，例如 https://servbay-kirby.local/panel。
2. 建立管理員帳號：首次瀏覽 /panel 網址時，會進入面板安裝頁。請依指示輸入所需資訊（使用者名稱、密碼、Email）來建立第一組管理員帳號。
3. 登入面板：完成建立後，即可登入 Kirby 管理面板，透過圖形介面管理您的網站內容。

使用 Kirby 建構網站

至此，您已成功於 ServBay 環境安裝並設定 Kirby，可開始善用其檔案導向特性，建構您的網站。以下介紹一些 Kirby 開發的基本概念與操作：

內容結構 (Content)

Kirby 的網站內容皆儲存於 content 資料夾。每一個頁面對應於 content 下的一個子資料夾。內容通常透過資料夾內的純文字檔案（如 page.txt）保存，並可採用類似 Markdown 的語法。

範例：建立「關於我們」頁面

於終端機中輸入：

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: 關於我們\n----\n這是關於我們的頁面內容。" > content/about/about.txt

然後瀏覽 https://servbay-kirby.local/about（若範本支援該頁）。

模板 (Templates)

所有模板檔位於 site/templates 目錄內，用於定義頁面呈現方式。檔名通常會與內容資料夾名稱或 Blueprint 名稱相對應（如 about.php 會對應 content/about 或使用 about Blueprint 的頁面）。

範例：建立 about.php 模板

於 site/templates/about.php 檔案：

<?php snippet('header') ?>

<main>
  <h1><?= $page->title() ?></h1>
  <div class="text">
    <?= $page->text()->kt() // 使用 KirbyText 進行渲染 ?>
  </div>
</main>

<?php snippet('footer') ?>

這裡運用了 snippet() 函式納入共用元件如頁首、頁尾等。

藍圖 (Blueprints)

Blueprint（藍圖）檔案存放於 site/blueprints，決定了面板中各頁面的欄位與設計，並採用 YAML 格式撰寫。

範例：建立 about.yml 藍圖

於 site/blueprints/pages/about.yml 檔案：

title: 關於頁面

columns:
  - width: 2/3
    fields:
      text:
        label: 內文字段
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # 側邊欄用的欄位，例如圖片上傳
      cover_image:
        label: 封面圖片
        type: files
        max: 1
        uploads:
          template: image

設定完成 blueprint 之後，您於面板新增「關於」頁時，便會看到這些自訂欄位。

片段 (Snippets)

片段為可重複利用的 PHP 檔案，常用於網站的頁首、頁尾、導覽列等部分，存放在 site/snippets 目錄。

控制器（Controllers）與模型（Models）

針對資料處理邏輯較複雜之頁面，可透過 site/controllers 目錄內的控制器處理頁面資料，自訂頁面類別則可於 site/models 目錄撰寫。

靜態資源（Assets）

CSS、JavaScript、圖片等靜態資源通常擺於專案根目錄下的 assets 資料夾。在模板中可透過 url('assets/...') 輔助函式取得對應資源網址。

範例：引用 CSS 與 JS

於 site/templates/default.php 或 site/snippets/header.php 內：

<link rel="stylesheet" href="<?= url('assets/css/style.css') ?>">
<script src="<?= url('assets/js/script.js') ?>"></script>

結語

經過上述步驟，您已在 ServBay 本機開發環境中成功安裝並設定 Kirby CMS。ServBay 所提供的整合式開發平台大幅簡化 PHP 應用的部署與管理，讓您能專注於運用 Kirby 靈活、檔案導向的強大功能來打造您的網站專案。接下來，您可進一步深入學習 Kirby 的模板、藍圖、片段等概念，建構更完整、複雜的網站結構與功能。