在 ServBay 環境中安裝與設定 Kirby CMS
Kirby 是一套靈活且強大的檔案導向內容管理系統(CMS),非常適合用來建置各類型網站。與傳統以資料庫為基礎的 CMS 不同,Kirby 直接將內容儲存在檔案系統中,因此相當輕量、易於版本控制並且部署便利。
本教學將引導您如何在專為開發者打造的本機 Web 開發環境——ServBay 中,透過 Composer 安裝並設定 Kirby 4.2 Starterkit。ServBay 已預先配置 PHP、Web 伺服器(如 Caddy 或 Nginx)和 Composer,是本機開發 Kirby 專案的理想平台。
前置條件
在開始之前,請確認您已完成以下事項:
- 已於 macOS 上安裝並執行 ServBay。
- 已於 ServBay 中啟用所需 PHP 版本(本例以 PHP 8.2 為例)。
- 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
3
步驟 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 應用中新增一組網站設定。
- 開啟 ServBay 應用程式:啟動 ServBay。
- 進入網站管理:點選 ServBay 視窗左側導覽欄的「網站」分頁。
- 新增網站:點擊畫面下方的「+」按鈕或類似新增網站的選項。
- 填寫網站資訊:於跳出的設定視窗中輸入下列資訊:
- 名稱:為您的網站命名(易辨識即可),例如
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
。
- 名稱:為您的網站命名(易辨識即可),例如
- 儲存設定:確認上述資訊無誤後,點擊儲存。ServBay 會自動套用新設定,並可能需重啟相關 Web 伺服器。
步驟 4:Kirby 基礎設定
Kirby 主要透過 site/config/config.php
檔進行核心設定。對於 Starterkit 來說,預設配置已足夠直接運作,您可於此檔案中加入自訂設定,例如:
- 啟用偵錯模式(
c::set('debug', true);
) - 設定面板語言
- 自訂路由規則等
您專案根目錄下的 content
資料夾會由 Starterkit 自動建立,專門用來存放網站所有頁面內容。
步驟 5:執行與存取您的 Kirby 網站
完成 ServBay 設定後,您即可用先前設定的網域方式存取您的 Kirby 網站。
- 確認 ServBay 正常運作:保證 ServBay 正在執行,且相關 Web 伺服器(Caddy 或 Nginx)與 PHP 套件皆已啟動。
- 網站瀏覽:開啟您的網頁瀏覽器,於網址列輸入您於步驟 3 設定的網域名稱,例如
https://servbay-kirby.local
。
您應該會看到 Kirby Starterkit 的預設歡迎頁。ServBay 預設啟用 HTTPS,故建議以 https://
存取。
步驟 6:安裝並使用 Kirby 面板(選用)
Kirby 提供強大的管理面板,方便網站內容、使用者與相關設定管理。
- 進入面板安裝頁:於瀏覽器輸入您的網站網域,並加上
/panel
路徑,例如https://servbay-kirby.local/panel
。 - 建立管理員帳號:首次瀏覽
/panel
網址時,會進入面板安裝頁。請依指示輸入所需資訊(使用者名稱、密碼、Email)來建立第一組管理員帳號。 - 登入面板:完成建立後,即可登入 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
2
3
然後瀏覽 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') ?>
2
3
4
5
6
7
8
9
10
這裡運用了 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
設定完成 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>
2
結語
經過上述步驟,您已在 ServBay 本機開發環境中成功安裝並設定 Kirby CMS。ServBay 所提供的整合式開發平台大幅簡化 PHP 應用的部署與管理,讓您能專注於運用 Kirby 靈活、檔案導向的強大功能來打造您的網站專案。接下來,您可進一步深入學習 Kirby 的模板、藍圖、片段等概念,建構更完整、複雜的網站結構與功能。