ServBay

繁體中文

English
简体中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano

繁體中文

English
简体中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano

Appearance

在 ServBay 環境中安裝與設定 Jigsaw ​

概述 ​

本文將指引您如何在強大的本機網頁開發環境 ServBay 中安裝並設定 Jigsaw 靜態網站產生器。ServBay 對 PHP、Node.js 等多元技術棧提供一站式整合，讓 Jigsaw 專案的架設過程大幅簡化。透過 ServBay，您可輕鬆為 Jigsaw 專案設定本地域名、HTTPS，以及高效能的 Web 伺服器，專注於網站內容開發。

什麼是 Jigsaw？ ​

Jigsaw 是由 Tighten 公司開發，基於 Laravel 元件構建的靜態網站產生器。它充分發揮 Laravel Blade 樣板引擎的強大與彈性，並結合 Markdown 格式，產製純靜態的 HTML 網站。Jigsaw 特別適合打造文件站、部落格、行銷頁面或任何不需後端資料庫及動態處理的網站。其主要優點如下：

  • 熟悉的工具鏈： 若您過去曾使用 Laravel 或 Blade 樣板，Jigsaw 將能快速上手。
  • 效能與安全兼具： 產生的靜態網站載入速度快，且無伺服端程式碼執行，安全性更高。
  • 靈活的樣板結構： 使用 Blade 可打造複雜版面與元件。
  • 內建 Markdown 支援： 內容撰寫輕鬆自在。

適用場景 ​

Jigsaw 特別適合以下需求：

  • 專案文件或 API 文件網站
  • 個人部落格或技術分享站
  • 企業或產品的行銷著陸頁
  • 小型形象展示網站
  • 任何重視效能與安全、內容較為固定的網站

前置準備 ​

開始作業前，請確保以下條件：

  1. 已安裝並啟動 ServBay： 您必須在 macOS 上安裝並啟動 ServBay。ServBay 已內建 PHP、Composer 與 Node.js/npm，這些都為 Jigsaw 須用工具。
  2. 具備基本終端機操作能力： 您需能在終端機執行基本指令。
  3. 了解 Composer 與 npm 的基本用法： Jigsaw 需使用 Composer 安裝，前端資產則依賴 npm 編譯。

安裝與設定流程 ​

本節將逐步說明如何於 ServBay 環境下安裝及設定 Jigsaw 專案。

步驟 1：建立專案目錄 ​

打開終端機，進入 ServBay 預設的網站根目錄 /Applications/ServBay/www，並為您的 Jigsaw 專案新建一個子資料夾。

bash
cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

此處我們將專案目錄命名為 servbay-jigsaw-demo，所有專案檔案將存放於此。

步驟 2：使用 Composer 建立 Jigsaw 專案 ​

ServBay 已預先安裝並設定好 Composer，可直接於終端機中使用 composer 指令。請在剛建立的專案目錄（/Applications/ServBay/www/servbay-jigsaw-demo）下運行 Composer 命令建立 Jigsaw 專案：

bash
composer create-project tightenco/jigsaw .

此指令將下載 Jigsaw 最新版本及其所有 PHP 相依套件至目前目錄（.）。請注意，結尾的點號 . 代表專案會建於當前資料夾，而不是另外建立一個子目錄。

步驟 3：設定 ServBay 網站 ​

若要在瀏覽器中存取 Jigsaw 網站，需在 ServBay 裡為此專案新增本機網站設定。

  1. 打開 ServBay UI： 雙擊 ServBay 應用圖示或由選單列圖示進入 ServBay 控制台。
  2. 切換至「網站」頁籤： 點選左側導覽列中的「網站」分頁。
  3. 新增網站： 點按底部的「+」按鈕並選「新增網站」。
  4. 填寫網站資訊：
    • 名稱 (Name)： 填寫方便辨識的名稱，如 ServBay Jigsaw Demo。
    • 域名 (Domain)： 輸入欲在本機存取的域名，建議以 .servbay.demo 結尾，避免與真實域名衝突（如 jigsaw-demo.servbay.demo）。ServBay 會自動將 .servbay.demo 解析指向本機。
    • 網站類型 (Site Type)： 選擇 PHP，因 Jigsaw 的建置過程需要 PHP 環境。
    • PHP 版本 (PHP Version)： 挑選一個已安裝的 PHP 版本，建議用較新穩定版。
    • 網站根目錄 (Site Root)： 這是關鍵步驟：Jigsaw 產出靜態檔案，預設會在專案根目錄下之 build_local 資料夾中。因此，請將網站根目錄指向此建置產出目錄： /Applications/ServBay/www/servbay-jigsaw-demo/build_local
  5. 儲存並套用設定： 填好所有資料後，按下「儲存」。ServBay 會提醒您應用變更，請按確認。系統會自動更新 Web 伺服器（Caddy 或 Nginx）設定，並為您配置 HTTPS。

步驟 4：安裝前端依賴 ​

多數 Jigsaw 專案會用 npm 管理／編譯前端資產（如 CSS 預處理器 SASS、JavaScript 等）。ServBay 已內建 Node.js 與 npm，可直接使用。

於專案資料夾（/Applications/ServBay/www/servbay-jigsaw-demo）執行以下指令安裝前端依賴：

bash
npm install

該命令會讀取根目錄下的 package.json，並下載需要的 Node.js 套件到 node_modules 資料夾。

步驟 5：建置 Jigsaw 網站 ​

裝妥所有依賴後，請使用 Jigsaw 的建置指令產生靜態網站檔案。

於專案資料夾內執行：

bash
./vendor/bin/jigsaw build

此指令的作用包括：

  1. 處理 source 資料夾內的 Markdown 檔案與 Blade 樣板。
  2. 執行 webpack.mix.js 中定義的前端編譯（若專案有使用 Laravel Mix）。
  3. 將最終產出的 HTML、CSS、JS 等靜態資產匯出至 build_local 資料夾。

步驟 6：存取您的網站 ​

目前，Jigsaw 網站的靜態檔案已經產生並儲於 /Applications/ServBay/www/servbay-jigsaw-demo/build_local。由於您已在 ServBay 將網站根目錄指向這裡，現在即可使用瀏覽器存取剛剛設定的本地域名。

請開啟瀏覽器，輸入於步驟 3 設定的網址，如 https://jigsaw-demo.servbay.demo。ServBay 會自動處理本機 HTTPS 憑證（採用 ServBay User CA），您應該能看到 Jigsaw 的預設歡迎頁。

客製化與開發 ​

至此，您已成功建置基礎環境，接下來可以自由客製 Jigsaw 網站內容與設計。

編輯內容與樣板 ​

  • 網站原始碼位於專案根目錄的 source 資料夾。
  • HTML 版型與元件皆採用 Blade 樣板，存於 source/_layouts 及 source/_partials。
  • 一般頁面內容多以 Markdown 撰寫，存於 source 或其子目錄（例：source/index.md, source/about.md）。
  • 部落格文章多放在 source/_posts，檔名格式為 YYYY-MM-DD-slug.md。

新增頁面／文章 ​

欲新增新頁面或部落格文章，只需於 source 或對應子資料夾（如 source/_posts）中建立新的 Markdown 檔案。

例如，新增一個 source/about.md：

markdown
---
title: "關於我們"
description: "瞭解 ServBay Jigsaw Demo 的更多資訊"
---

# 關於我們

這是一個使用 Jigsaw 製作的關於頁面。

您可在這裡放入公司介紹、團隊資訊等內容。

客製化樣式與腳本 ​

Jigsaw 專案多透過 Laravel Mix（webpack.mix.js）來編譯前端資產。

  • 樣式（通常為 SASS/SCSS）存於 source/_assets/sass
  • JavaScript 檔案置於 source/_assets/js

可在專案目錄中，使用 npm script 編譯前端資產：

  • npm run dev：以開發模式進行資產編譯（含 Source Maps、不壓縮）
  • npm run watch：開發模式編譯且自動監控檔案異動，利於開發
  • npm run prod：產生適用於正式環境的最終檔案（壓縮並優化）

舉例：若修改了 source/_assets/sass/main.scss，即可運行 npm run dev 或 npm run watch，編譯出對應的 CSS 檔案。

重新建置網站 ​

重要提醒： 每次您修改 source 資料夾中的**內容檔（Markdown）或樣板檔（Blade）**後，都必須重新執行 Jigsaw 的建置指令，才能讓 Jigsaw 處理這些變更、同步產生於 build_local：

bash
./vendor/bin/jigsaw build

若您變更的是前端資產（SASS、JS），則需運行 npm run dev 或 npm run watch 重新編譯前端檔案。多數 Jigsaw 專案內的 build 指令也會自動觸發 Mix 編譯，但分開操作更易調試。

注意事項 ​

  • 建置輸出目錄： Jigsaw 預設產出於 build_local（開發用）與 build_production（正式用）。請確保 ServBay 網站根目錄已對應到您實際欲瀏覽的目錄（本地開發通常選擇 build_local）。
  • Web 伺服器運作： ServBay 採用 Caddy 或 Nginx，直接支援 build_local 內的靜態資源，效能高且穩定。無需再啟用 Jigsaw 內建的 jigsaw serve（它僅為快速預覽，功能不及 ServBay 的完整 Web 服務）。
  • HTTPS 支援： ServBay 自動為 .servbay.demo 網域套用 HTTPS，並以 ServBay User CA 簽發。本機測試建議您信任這組 CA 憑證，避免瀏覽器跳出警告。
  • 乾淨建置： 若遇到異常建置問題，可嘗試指令 ./vendor/bin/jigsaw build --clean 重新產生乾淨結果。

常見問題集（FAQ） ​

問：我已修改 Markdown 檔案，為何瀏覽器無法即時看到更新？

答：每當內容或樣板異動後，請於終端機重新運行 ./vendor/bin/jigsaw build，以建置並同步更新網站。

問：我已變更 SCSS，卻沒看到樣式異動？

答：請於專案目錄運行 npm run dev 或 npm run watch，重新編譯前端資產。

問：造訪本地域名時出現「無法存取」或「找不到檔案」訊息？

答：請檢查下列幾點：

  1. 確認 ServBay 已啟動。
  2. 核對 ServBay 網站設定：域名填寫是否正確？是否確實將網站根目錄指向 /Applications/ServBay/www/servbay-jigsaw-demo/build_local？
  3. 確認已執行 ./vendor/bin/jigsaw build，且 build_local 下已產生靜態檔（如 index.html）。

問：要如何部署 Jigsaw 網站？

答：Jigsaw 產出純靜態檔案。部署流程如下：

  1. 執行 ./vendor/bin/jigsaw build production，建置優化過的正式版檔案。
  2. 將 build_production 內全部檔案，上傳至任一支援靜態網站的主機（如 Netlify、Vercel、GitHub Pages，各式雲端儲存等）。

總結 ​

依靠 ServBay，在 macOS 下安裝與設定 Jigsaw 靜態網站產生器變得簡單又高效。ServBay 提供完整所需執行環境（PHP、Composer、Node.js、npm）以及卓越本機 Web 伺服器配置能力。依循本指南，您即能以最快速度啟動 Jigsaw 專案，並充分運用 ServBay 各項功能，優化您的本機開發流程。