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

概述

Craft CMS 是一套功能強大的內容管理系統（CMS），以靈活的內容建模、直覺的操作介面，以及開發者友善的特性廣受開發者喜愛。它非常適合打造複雜且可自訂的網站。

使用 ServBay 作為 Craft CMS 的本地開發環境，有許多優勢，包括預先配置好的 PHP、資料庫（如 MySQL 或 PostgreSQL）與網頁伺服器（Caddy 或 Nginx），還有內建的 Composer 及命令列工具，極大地簡化了安裝與設定流程。

本指南將為你詳細介紹如何在 ServBay 環境中安裝並設定 Craft CMS 專案。

前置條件

在開始之前，請確認你已經具備下列條件：

ServBay 已安裝並執行： 請確保你已在 macOS 成功安裝好 ServBay，且所需的 PHP 版本（Craft CMS 有版本需求，請參考 Craft CMS 官方文件）與資料庫（通常為 MySQL 或 PostgreSQL）套件已啟動。ServBay 支援多版本 PHP 和多種資料庫，你可依 Craft CMS 需求靈活切換與設定。
熟悉基本指令列操作： 你將需用終端機執行部份指令，如建立資料夾與執行 Composer。
了解 Composer： Craft CMS 以 Composer 做為依賴管理工具。ServBay 已經內建 Composer，你需要了解如何執行 composer create-project 等指令。

安裝 Craft CMS 的流程

以下是在 ServBay 中安裝與設定 Craft CMS 的具體步驟。

步驟 1：建立專案資料夾

首先，在 ServBay 的預設網站根目錄 /Applications/ServBay/www 下建立新的專案資料夾。ServBay 會將這個資料夾設為 Web 伺服器的服務根目錄，讓你可直接存取專案。

打開終端機，輸入以下指令：

bash

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

這會在 /Applications/ServBay/www 下新建名為 servbay-craft-app 的資料夾，並進入該目錄。

步驟 2：透過 Composer 建立 Craft CMS 專案

ServBay 已內建 Composer，因此你可直接在專案資料夾裡用 Composer 安裝 Craft CMS。Craft CMS 官方建議用 Composer 安裝。

在 servbay-craft-app 資料夾裡執行：

bash

composer create-project craftcms/craft .

此指令會下載最新版 Craft CMS 及其所有相依套件到目前目錄（.）。請耐心等候 Composer 完成下載與安裝。

步驟 3：建立資料庫與使用者

Craft CMS 需要一個資料庫來儲存內容與設定。我們將利用 ServBay 內建的 phpMyAdmin 或 Adminer 建立資料庫與使用者。以下以 phpMyAdmin 為例：

進入 ServBay 的資料庫管理工具 (phpMyAdmin)
打開瀏覽器，訪問 ServBay 的本機開發面板 https://servbay.host/。在面板找到並點選「phpMyAdmin」連結。
提示：ServBay 預設的 phpMyAdmin 登入帳號通常為 root，密碼是 ServBay.dev。為了安全，建議你登入後立即修改 root 密碼或新建專用管理帳號。
新增資料庫用戶
雖然你可以用 root 來連接 Craft CMS，但出於安全與權限管理考量，最佳做法是為每個應用建立專屬的資料庫使用者。
1. 前往使用者帳號頁面
  在 phpMyAdmin 首頁，點選上方「使用者帳號」選單。
2. 新增使用者帳號
  點選「新增使用者帳號」，填寫以下資訊：
  - 使用者名稱： 輸入一組專屬於 Craft CMS 使用的資料庫用戶名稱，例如 craft_user。
  - 主機名稱： 選擇 localhost 或「本地」，代表此用戶只能由本機連線。
  - 密碼： 輸入安全密碼。請勿使用 password123 等範例密碼，尤其在生產環境。如僅本地測試可用較簡單密碼，但務請留意安全性。
  - 再次輸入： 再一次輸入密碼確認無誤。
  - 在「建立與使用者同名的資料庫並授與全權」區塊，選取「建立與使用者同名的資料庫並全部授權」，這會自動產生一個名為 craft_user 的資料庫，並給予該用戶全部權限。
  - 請務必勾選「授予所有權限」。
  - 最後，點頁面下方的「執行」按鈕。
此時，你已建立名為 craft_user 的資料庫用戶，以及同名的資料庫 craft_user 並授予相關權限。

步驟 4：設定 Web 伺服器（於 ServBay 中建立網站）

為了讓 ServBay 的 Web 伺服器（Caddy 或 Nginx）能服務於你的 Craft CMS 專案，需在 ServBay 新增「網站」設定。

啟動 ServBay 應用程式
開啟 ServBay。
新增網站
點選 ServBay 視窗左側的「網站」標籤（舊版可能顯示為「主機」）。點下方「+」或右側「新增網站」來建立新網站配置。
填寫以下內容：
- 名稱（Name）： 輸入一個好辨識的網站名稱，如 My Craft Site。
- 網域（Domains）： 輸入你希望用於本機訪問的網域，如 servbay-craft.local。ServBay 會自動配置本機 DNS，方便訪問。
- 網站類型（Type）： 選擇 PHP。
- PHP 版本（PHP Version）： 請選擇你在前置條件確認、與 Craft CMS 相容的 PHP 版本。ServBay 支援多版本並行。
- 網站根目錄（Website Root）： 這一步非常關鍵。Craft CMS 可公開訪問的檔案（如 index.php）位於專案資料夾的 web 子目錄。為了安全，Web 伺服器的根目錄應指向 web 資料夾，而非整個專案目錄。請鮮明設定路徑為： /Applications/ServBay/www/servbay-craft-app/web 請確認路徑正確，指向你在步驟 1 建立的專案目錄下的 web 資料夾。
儲存設定
全部設定好後，點選「儲存」。ServBay 會自動重新載入伺服器設定，新網站將即時生效。你可以於 ServBay 「網站」列表中看到新設定的 servbay-craft.local 網站。

步驟 5：執行 Craft CMS 安裝程式

現在，可以透過瀏覽器開啟你設定的網域，來啟動 Craft CMS 的安裝精靈。

進入安裝頁面
打開瀏覽器，訪問剛剛設定的網域 https://servbay-craft.local/。Craft CMS 會偵測到尚未安裝，並自動導向安裝頁面，通常為 https://servbay-craft.local/index.php?p=admin/install。
填寫資料庫連接資訊
在安裝頁面的資料庫配置步驟，輸入你在步驟 3 建立的資料庫資訊：
- 資料庫伺服器（Database Server）： localhost
- 資料庫名稱（Database Name）： craft_user（或你建立的資料庫名稱）
- 使用者名稱（Username）： craft_user（或你建立的使用者名稱）
- 密碼（Password）： 你剛才為 craft_user 設定的密碼。
點選繼續。Craft CMS 會嘗試連接資料庫，若成功則進到下一步。
建立管理員帳號
依操作指示輸入 Craft 的管理員資訊：使用者名稱、密碼與電子郵件。密碼請選擇足夠安全者。
點選繼續。
網站設定
輸入你的網站名稱等基本資訊。
點選「完成安裝（Finish Up）」按鈕。Craft CMS 會自動完成最後一哩安裝，包括建立資料表、產生設定檔。
安裝完畢後，即會導向 Craft CMS 管理後台登入頁。

步驟 6：初步設定與探索

登入 Craft CMS 管理後台，你可進行初步環境與功能設定：

檢查 .env 檔： Craft CMS 以 .env 檔管理環境變數，包括資料庫連線設定。安裝程式會於（servbay-craft-app/）產生一份。你可直接修改，如將 CRAFT_ENVIRONMENT 設為 dev。
安裝外掛： 後台點選「插件（Plugins）」可瀏覽、安裝及管理 Craft CMS 外掛來擴充功能。
建立內容結構： 探索「設定（Settings）」區塊，定義內容欄位、分區（Sections）、分類（Categories）、標籤（Tags）等資料結構。
郵件發送設定： 若需在本地測試郵件功能，可設定 Craft CMS 使用 ServBay 內建的 Mailpit 或 Mailhog。於 .env 檔或管理後台郵件設定區，將郵件方式設為 SMTP，伺服器地址通常為 localhost，端口填 Mailpit/Mailhog SMTP 端口（可於 ServBay 面板查閱）。

常見問題（FAQ）

問：安裝過程遇到資料庫連接錯誤怎麼辦？
- 答：請檢查安裝時輸入的資料庫伺服器位址（localhost）、資料庫名稱、用戶名稱及密碼是否完全正確，且 ServBay 的資料庫服務（如 MySQL 或 PostgreSQL）確實已執行。
問：訪問 servbay-craft.local 時出現 404 或空白頁？
- 答：
  - 請確認 ServBay 中「網站根目錄」是否正確指向 /Applications/ServBay/www/servbay-craft-app/web。這是最常見的錯誤來源。
  - 確認 ServBay 的 Web 伺服器（Caddy 或 Nginx）及 PHP 已運作中。
  - 查看 ServBay 網站列表中 servbay-craft.local 設定是否已啟用。
問：用 Composer 安裝 Craft CMS 時速度緩慢或安裝失敗？
- 答：多半是網路或 Composer 鏡像源問題。可考慮將 Composer 鏡像切換成國內站點，如阿里雲或 Packagist China。
問：安裝後管理後台或前台頁面樣式亂掉或圖片無法顯示？
- 答：這通常與檔案權限有關。請確保 ServBay 執行用戶對 storage、web/cpresources 等目錄擁有寫入權限。ServBay 通常會自動處理，但若遇問題可嘗試手動檢查或重設目錄權限。

總結

按照以上步驟，你應已成功在 ServBay 本機開發環境安裝並設定好 Craft CMS。ServBay 提供的整合環境，讓 PHP 版本管理、資料庫設定與網頁伺服器配置變得更簡單，讓你能專注於 Craft CMS 應用開發。現在，你可以開始善用 Craft CMS 強大的內容建模功能，開發專屬於你的網站或應用程式！

在 ServBay 環境中安裝與設定 Craft CMS ​

概述 ​

前置條件 ​

安裝 Craft CMS 的流程 ​

步驟 1：建立專案資料夾 ​

步驟 2：透過 Composer 建立 Craft CMS 專案 ​

步驟 3：建立資料庫與使用者 ​

步驟 4：設定 Web 伺服器（於 ServBay 中建立網站） ​

步驟 5：執行 Craft CMS 安裝程式 ​

步驟 6：初步設定與探索 ​

常見問題（FAQ） ​

總結 ​