Memasang dan Mengkonfigurasi Sculpin dalam Persekitaran ServBay

Pengenalan

Sculpin ialah penjana laman web statik berasaskan PHP yang berkuasa dan fleksibel, sesuai untuk membina blog, laman dokumentasi atau sebarang projek yang memerlukan penukaran kandungan dinamik (seperti templat Twig dan fail Markdown) kepada halaman HTML statik yang berprestasi tinggi. Ia menggunakan Composer sebagai pengurus kebergantungan dan dibina berasaskan komponen Symfony, menyediakan pengalaman pembangunan yang stabil dan mesra untuk pembangun.

ServBay merupakan persekitaran pembangunan web tempatan berasaskan macOS yang diintegrasi dengan pelbagai pakej popular seperti PHP, Composer, pangkalan data (MySQL, PostgreSQL, MongoDB, Redis), pelayan web (Caddy, Nginx) serta antara muka grafik mesra pengguna untuk pengurusan. Dengan ServBay, anda boleh mempermudah proses persediaan persekitaran pembangunan Sculpin di macOS, terutamanya dari segi pengurusan versi PHP, kebergantungan projek serta konfigurasi pelayan web.

Panduan ini menerangkan langkah demi langkah cara memasang dan mengkonfigurasi Sculpin dalam ServBay, serta bagaimana menyediakan laman pembangunan tempatan anda.

Senario Penggunaan

• Membina blog statik berprestasi tinggi dengan timbunan teknologi PHP.
• Menjana laman dokumentasi statik untuk projek sumber terbuka atau produk anda.
• Menyediakan halaman pemasaran atau laman korporat tanpa keperluan pangkalan data belakang.
• Menulis kandungan dengan templat Twig dan Markdown, sambil menikmati kelajuan dan keselamatan laman statik.

Prasyarat

Sebelum memulakan, pastikan anda telah memenuhi syarat berikut:

1. ServBay telah dipasang dan berjalan di sistem macOS anda. ServBay menyediakan persekitaran PHP, pengurus kebergantungan Composer, dan pelayan web (Caddy atau Nginx) yang diperlukan.
2. Memiliki pengetahuan asas penggunaan baris perintah.
3. Memahami konsep asas PHP, Composer, dan Markdown.

Langkah-langkah Pemasangan Sculpin

Berikut adalah langkah terperinci untuk memasang dan mengkonfigurasi Sculpin dalam persekitaran ServBay:

Langkah 1: Cipta Direktori Projek

Mula-mula, buat direktori projek baru di direktori root laman ServBay (/Applications/ServBay/www). Di sini, kita akan gunakan servbay-sculpin-app sebagai nama projek contoh.

Buka terminal dan jalankan arahan berikut:

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

Direktori ini akan menempatkan semua fail projek Sculpin anda.

Langkah 2: Cipta Projek Sculpin dengan Composer

ServBay sudah dilengkapi dengan Composer, jadi tiada pemasangan tambahan diperlukan. Anda boleh terus menggunakan perintah composer di terminal.

Kita akan menggunakan rangka-blog rasmi daripada Sculpin untuk mula dengan lebih pantas. Di dalam direktori servbay-sculpin-app yang baru dibuat tadi, jalankan arahan Composer berikut:

composer create-project sculpin/sculpin-blog-skeleton .

Arahan ini akan memuat turun rangka-blog Sculpin dan semua kebergantungan ke direktori semasa (.).

Langkah 3: Konfigurasi Laman Web ServBay

Untuk membolehkan pelayan web ServBay (Caddy atau Nginx) menghidangkan laman Sculpin anda, anda perlu menambah konfigurasi laman web di dalam ServBay.

1. Buka aplikasi ServBay: Lancarkan antara muka grafik ServBay.
2. Pergi ke tab "Laman Web": Klik tab "Laman Web" di bar navigasi aplikasi ServBay.
3. Tambahkan laman baru: Klik butang "+" di bahagian kiri bawah untuk menambah konfigurasi laman web baru.
4. Isikan maklumat laman:
   • Nama (Name): Masukkan nama mudah dikenali, contohnya My Sculpin Site.
   • Domain: Masukkan domain tempatan yang anda ingin gunakan, contohnya servbay-sculpin.local. ServBay secara automatik akan mengkonfigurasi resolusi tempatan dan sijil SSL (menggunakan ServBay User CA) untuk domain .local.
   • Jenis Laman (Type): Pilih PHP kerana Sculpin adalah aplikasi PHP.
   • Versi PHP (PHP Version): Pilih versi PHP yang anda ingin gunakan. ServBay menyokong pelbagai versi PHP—pilih satu yang serasi dengan Sculpin (biasanya versi terbaru sudah mencukupi).
   • Root Direktori (Document Root): Langkah ini penting. Fail statik yang dihasilkan oleh Sculpin secara lalai diletakkan di dalam direktori output_dev atau output_prod projek. Untuk pembangunan lokal, tetapkan root direktori laman web kepada: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Simpan konfigurasi: Selesai mengisi maklumat, klik butang "Simpan". ServBay akan secara automatik mengaplikasikan konfigurasi baru ke pelayan webnya (Caddy atau Nginx). Biasanya, anda tidak perlu restart servis secara manual.

Langkah 4: Bina Laman Sculpin

Selepas konfigurasi laman web dalam ServBay selesai, anda perlu membenarkan Sculpin untuk menjana fail statiknya.

Di terminal, pastikan anda berada di root projek /Applications/ServBay/www/servbay-sculpin-app, kemudian jalankan arahan berikut untuk memasang kebergantungan projek (jika sudah laksanakan Langkah 2, langkah ini mungkin tidak wajib, tetapi menjalankannya sekali memastikan semua kebergantungan benar-benar dipasang):

composer install

Seterusnya, jalankan perintah Sculpin untuk membina laman web:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Laluan ke fail boleh-laksana Sculpin yang dipasang melalui Composer.
• generate: Perintah utama untuk janaan laman web statik. Ia akan membaca kandungan dan templat dari direktori source dan mengoutput fail statik ke direktori output yang telah dikonfigurasi (lalainya output_dev).
• --watch: Flag ini membolehkan Sculpin memantau perubahan pada fail dalam direktori source. Setiap kali fail diubah, Sculpin akan secara automatik menjana semula laman—sangat berguna ketika pembangunan.

Setelah arahan berjaya dijalankan dan memaparkan "Sculpin has generated your site!" atau mesej seumpamanya, fail statik akan tersedia di direktori output_dev.

Langkah 5: Akses Laman Pembangunan Tempatan

Kini, anda boleh melayari laman Sculpin anda dengan domain yang dikonfigurasi dalam ServBay.

Buka pelayar web dan lawati domain yang telah anda tetapkan dalam Langkah 3:

https://servbay-sculpin.local

Oleh kerana root direktori laman web anda di ServBay telah ditetapkan ke output_dev, dan perintah sculpin generate --watch sedang berjalan serta memantau perubahan, anda kini boleh melihat secara langsung sebarang suntingan pada kandungan atau templat dengan hanya melawat https://servbay-sculpin.local. ServBay juga menyediakan sijil SSL automatik agar laman boleh diakses secara selamat melalui HTTPS di tempatan.

Pembangunan dengan Sculpin

Setelah anda berjaya memasang dan mengkonfigurasi Sculpin dalam ServBay, anda sudah boleh mula membangunkan laman web statik anda. Berikut asas operasi pembangunan:

Gambaran Struktur Projek Sculpin

Memahami struktur asas projek Sculpin akan membantu proses pembangunan anda:

servbay-sculpin-app/
├── app/                # Konfigurasi aplikasi & cache
├── output_dev/         # Direktori output fail statik untuk pembangunan (root laman ServBay perlu tunjuk sini)
├── output_prod/        # Direktori output fail statik untuk produksi
├── source/             # Fail sumber laman (kandungan Markdown, templat Twig, aset statik)
│   ├── _layouts/       # Fail layout Twig
│   ├── _posts/         # Fail blog post dalam Markdown
│   ├── assets/         # Aset statik (CSS, JS, imej, dsb.)
│   └── index.md        # Fail halaman utama dalam Markdown
├── vendor/             # Kebergantungan yang dipasang Composer
├── sculpin.yml         # Fail konfigurasi utama Sculpin
├── composer.json       # Fail konfigurasi kebergantungan Composer
└── ...fail lain

Kerja utama anda akan berlaku dalam direktori source.

Menulis Entri Blog Baru

Untuk menambah entri blog baru di laman Sculpin, hanya perlu cipta fail Markdown baru dalam direktori source/_posts. Nama fail lazimnya menggunakan format YYYY-MM-DD-slug.md.

Sebagai contoh, cipta fail 2024-06-06-my-first-post.md:

---
title: "Artikel Pertama Saya"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# Artikel Pertama Saya

Ini ialah kandungan artikel blog Sculpin pertama saya. Di sini saya berkongsi pengalaman menggunakan ServBay dan Sculpin.

Anda boleh menulis kandungan menggunakan sintaks Markdown di sini.

## Sub-judul

Senarai:
- Item 1
- Item 2

Selepas anda menyimpan fail ini, kerana sculpin generate --watch sedang berjalan, Sculpin akan mengesan perubahan secara automatik lalu membina semula laman. Hanya muat semula https://servbay-sculpin.local di pelayar web untuk melihat artikel baru.

Cipta Halaman Baharu

Untuk menambah laman bebas seperti "Tentang Kami", buat fail Markdown baru terus dalam direktori source, contoh: about.md:

---
title: "Tentang Kami"
layout: page.html.twig # Spesifikasikan fail layout yang digunakan
---

# Panduan ServBay Sculpin

Halaman ini merupakan panduan membina laman web statik menggunakan ServBay dan Sculpin.

Selepas menyimpan, Sculpin akan menjana fail output_dev/about/index.html (jika telah diaktifkan URL 'cantik'). Anda boleh akses melalui https://servbay-sculpin.local/about/.

Menyesuaikan Gaya dan Skrip

Aset statik seperti fail CSS dan JavaScript biasanya diletakkan dalam direktori source/assets. Anda boleh edit terus fail-fail ini.

Sebagai contoh, lakukan perubahan pada source/assets/css/style.css untuk mengubah gaya laman web.

Semua aset ini akan disalin ke direktori output semasa proses penjanaan laman. Jika anda mengubah fail ini, fungsi --watch dalam Sculpin juga akan mengesan dan memicu penjanaan semula.

Membina Laman Untuk Produksi

Apabila laman anda sudah sedia untuk diterbitkan ke persekitaran produksi, adalah penting untuk membina versi yang dioptimumkan. Biasanya, proses produksi melibatkan kompresi aset dan pelbagai pengoptimuman.

Gunakan perintah berikut untuk membina versi produksi:

vendor/bin/sculpin generate --env=prod

Arahan ini akan menghasilkan fail statik ke dalam direktori output_prod. Anda boleh memuat naik semua fail dari output_prod ke mana-mana servis hosting laman statik (cth. GitHub Pages, Netlify, Vercel, atau pelayan web anda sendiri).

Jika ingin menyemak hasil produksi secara lokal melalui ServBay, ubah root direktori laman web dalam konfigurasi ServBay ke /Applications/ServBay/www/servbay-sculpin-app/output_prod, kemudian simpan dan akses domain seperti biasa.

Perhatian

• Pastikan ServBay sedang aktif dan laman web telah diaktifkan dalam konfigurasi.
• Sahkan bahawa sculpin generate --watch sedang berjalan dalam terminal, supaya laman dikemaskini automatik semasa pembangunan.
• Pastikan root direktori laman web di ServBay menunjuk ke direktori output Sculpin yang betul (semasa pembangunan biasanya output_dev).
• ServBay secara automatik menyediakan sijil SSL untuk domain .local, tetapi sistem operasi anda mungkin perlu mempercayai ServBay User CA. Sila rujuk dokumentasi rasmi ServBay untuk langkah-langkahnya.

Soalan Lazim (FAQ)

S: Saya telah mengubah fail, tetapi laman tidak dikemaskini?

J: Pastikan anda telah menjalankan arahan vendor/bin/sculpin generate --watch dalam direktori projek dan tiada ralat yang menyebabkan arahan itu terhenti. Semak juga keluaran di terminal untuk sebarang mesej kesilapan. Cuba kosongkan cache pelayar atau guna mod privasi.

S: Saya mendapat ralat SSL bila melawat https://servbay-sculpin.local?

J: Ini kerana ServBay menjana sijil self-signed untuk domain .local yang memerlukan sistem operasi mempercayai ServBay User CA. Ikuti panduan dalam dokumentasi ServBay untuk pemasangan dan mempercayai CA sijil tersebut.

S: Bagaimana untuk menukar versi PHP?

J: Anda boleh memasang serta mengurus pelbagai versi PHP melalui tab "Pakej" di aplikasi ServBay. Kemudian, dalam tab "Laman Web", sunting konfigurasi laman Sculpin anda dan pilih versi PHP yang diingini sebelum menyimpan.

S: Apakah enjin templat dan bahasa penanda yang disokong Sculpin?

J: Secara lalai, Sculpin menggunakan Twig sebagai enjin templat dan menyokong Markdown secara meluas untuk penulisan kandungan.

Kesimpulan

Dengan persekitaran bersepadu yang disediakan oleh ServBay, pemasangan dan konfigurasi penjana laman web statik Sculpin di macOS menjadi sangat mudah dan efisien. PHP dan Composer pra-pasang, pelayan web yang mudah dikonfigurasi serta ciri SSL automatik ServBay menyediakan asas yang kukuh untuk pembangunan tempatan Sculpin. Dengan mengikuti panduan ini, anda boleh dengan cepat menyiapkan persekitaran pembangunan Sculpin dan membina serta menguji projek laman web statik anda secara efisien. Gabungan kekuatan Sculpin dan kemudahan yang ditawarkan ServBay membolehkan anda fokus menghasilkan kandungan berkualiti tanpa perlu bimbang tentang konfigurasi persekitaran pembangunan yang rumit.