Nota premium: Ini panduan untuk menghasilkan susunan yang digunakan oleh laman ini, bukan sekadar laman contoh yang berhenti pada paparan “Hello World”. Blog ditulis dalam Markdown, dibina menjadi HTML statik, kemudian dihantar sebagai aset Cloudflare Worker. Borang hubungi menggunakan Worker, D1 dan Turnstile. Jika anda hanya mahu blog, anda boleh berhenti selepas langkah 10 dan menambah borang kemudian.
Sediakan lebih kurang satu petang untuk setup pertama. Nama butang dalam dashboard mungkin berubah, jadi fahami tujuan setiap langkah: kod tinggal dalam Git, proses build menghasilkan _site, dan Worker menghantar fail itu kepada pembaca.
1. Buka akaun yang diperlukan
Daftar akaun Cloudflare dan GitHub. Sahkan alamat e-mel kedua-duanya, aktifkan pengesahan dua faktor, dan simpan akses pemulihan di tempat selamat. GitHub menyimpan kod; Cloudflare membina dan menghidangkan laman. Anda juga memerlukan domain jika mahu alamat sendiri, tetapi alamat workers.dev sudah cukup untuk percubaan pertama.
2. Pasang alat kerja di komputer
Pasang Git dan Node.js versi LTS semasa. Dalam Terminal, semak git --version, node --version dan npm --version. Editor seperti VS Code memudahkan suntingan, tetapi bukan syarat. Pilih satu folder kerja yang mudah dicari; elakkan menyimpan projek di dalam folder yang disegerakkan secara agresif semasa build berjalan.
3. Tentukan nama repo dan identiti Git
Buat repository kosong di GitHub, contohnya laman-peribadi; jangan tambah README automatik jika anda akan menolak salinan projek yang sudah ada. Untuk kerja lokal, set nama serta e-mel Git dengan git config --global user.name "Nama Anda" dan git config --global user.email "anda@example.com". Gunakan e-mel yang memang anda kawal. Salin atau clone sumber projek ini yang anda mempunyai akses kepadanya, kemudian masuk ke foldernya dengan cd NAMA_FOLDER. Panduan seterusnya menggunakan fail sumber projek ini sebagai titik mula; ia bukan arahan membina semua HTML dan JavaScript dari halaman kosong.
Jika folder salinan belum ada sejarah Git, jalankan git init dan git branch -M main. Jika ia hasil clone repo asal, sejarah serta origin asal sudah ada. Dalam kedua-dua keadaan, sambungkan repo milik anda: gunakan git remote add origin URL_REPO_ANDA jika belum ada origin, atau git remote set-url origin URL_REPO_ANDA jika mahu mengganti remote asal. Semak dengan git remote -v sebelum push. Pilih URL HTTPS atau SSH mengikut cara akses GitHub yang sudah anda sediakan.
Jangan letak kata laluan, token API atau secret dalam repo. Masukkan node_modules/, _site/, .wrangler/ dan .dev.vars* ke .gitignore. Fail _site ialah hasil build; sumber sebenar ialah HTML, CSS, JavaScript, Markdown dan konfigurasi.
4. Kenali struktur projek sebelum mengubahnya
Di repo ini, index.html ialah homepage, assets/ menyimpan gaya, skrip dan gambar, blog-src/post/ serta blog-src/posts/ menyimpan artikel, scripts/build-blog.mjs menukar Markdown menjadi halaman blog, dan worker.js mengendalikan permintaan. wrangler.jsonc menyatakan nama Worker, folder aset _site dan ikatan pangkalan data. schema.sql pula membina jadual mesej borang.
Anda tidak perlu menghafal semua fail. Satu aturan yang penting: sunting sumber, bukan halaman yang telah dijana di blog/ atau _site/. Build seterusnya akan menulis semula hasil tersebut.
Sebelum menerbitkan salinan sendiri, tukar nama, pautan sosial, teks homepage, domain dalam scripts/build-blog.mjs dan widget Turnstile. Jika anda mahu mengekalkan borang, cipta D1 milik akaun sendiri pada langkah 8. Jika tidak mahu borang, buang atau gantikan aliran itu secara lengkap; jangan biarkan borang yang kelihatan aktif tetapi sebenarnya menghantar ke pangkalan data lama.
5. Pasang pakej dan bina di komputer
Dalam folder utama projek, jalankan npm install, kemudian npm run build. Skrip build membersihkan hasil lama, menjana halaman artikel, menyalin fail laman ke _site, dan mengurus versi aset. Jika build gagal, baca ralat pertama dahulu. Ralat yang biasa ialah format metadata Markdown tidak lengkap, nama fail berganda atau laluan gambar salah.
Untuk melihat hasilnya, jalankan python3 -m http.server 8788 --directory _site dan buka http://localhost:8788. Buka homepage, /blog/, satu artikel dan satu halaman tools. Tekan Ctrl+C apabila selesai. Setiap kali kandungan berubah, jalankan semula npm run build sebelum memuat semula paparan.
6. Tulis artikel Markdown pertama
Salin blog-src/post-template.md kepada fail bernama seperti 2026-10-13-catatan-pertama.md dalam blog-src/post/. Tarikh pada nama fail dan medan date perlu sepadan dengan tarikh terbit sebenar. Isi title, description dan tags, diikuti beberapa perenggan yang benar-benar membantu pembaca. Nama selepas tarikh menjadi alamat artikel, contohnya /blog/catatan-pertama/, jadi pilih slug yang stabil.
Simpan gambar dalam assets/blog/ dan panggil dengan laluan mutlak laman, seperti . Semak ejaan dan huruf besar kecil. Build akan mengemaskini senarai blog, tag, carian, RSS, sitemap dan empat artikel terkini di homepage.
7. Sediakan konfigurasi Worker
Dalam wrangler.jsonc, letakkan nama Worker milik anda dan pastikan assets.directory menunjuk ke ./_site. main menunjuk ke ./worker.js. Kod Worker dalam projek ini menghantar /api/contact ke pengendali borang dan permintaan lain ke env.ASSETS.fetch(request). Ini membolehkan satu deployment mengendalikan laman statik serta API ringkas. Semak panduan Wrangler dan Worker apabila sintaks konfigurasi berubah.
Pasang atau jalankan Wrangler melalui npx wrangler. Semak npx wrangler --version dan log masuk dengan npx wrangler login. Pada setup pertama, pelayar akan membuka kebenaran akaun Cloudflare. Jalankan npx wrangler dev untuk mencuba Worker di komputer selepas build siap. Jangan anggap paparan static server sahaja sudah menguji API borang; laluan itu memerlukan Worker.
8. Tambah D1 jika mahu borang hubungi
Bina pangkalan data dengan npx wrangler d1 create mzulkamal-contact, atau tukar nama kepada pilihan anda. Salin database_id yang diberi ke wrangler.jsonc, dalam d1_databases, dengan binding bernama DB kerana kod projek ini menggunakan env.DB. Jangan salin ID pangkalan data orang lain; setiap akaun mempunyai ID tersendiri. Dokumentasi D1 menerangkan hubungan binding tersebut.
Jalankan npx wrangler d1 execute mzulkamal-contact --local --file=./schema.sql untuk cubaan lokal, kemudian npx wrangler d1 execute mzulkamal-contact --remote --file=./schema.sql untuk pangkalan data sebenar. --remote menyentuh data produksi; pastikan fail skema telah dibaca dahulu. Skema ini membuat jadual contact_messages serta indeks tarikh. Jika mahu laman tanpa borang, jangan paparkan borang yang belum berfungsi.
9. Lindungi borang dengan Turnstile
Dalam Cloudflare, cipta widget Turnstile untuk domain anda. Tukar data-sitekey di index.html kepada site key milik anda. Simpan secret key sebagai secret runtime Worker dengan npx wrangler secret put TURNSTILE_SECRET_KEY, bukan dalam Git atau pemboleh ubah build biasa. Pengendali dalam functions/api/contact.js menghantar token ke Siteverify dan menyemak hostname serta action sebelum menyimpan mesej. Widget sahaja tidak memadai; pengesahan pada server ialah bahagian penting.
Untuk ujian localhost, gunakan pasangan key ujian yang disediakan Cloudflare dan .dev.vars lokal. Pastikan key produksi dipulihkan sebelum commit. Hantar satu mesej ujian selepas deploy, kemudian semak rekod D1. Jika borang gagal, periksa domain widget, binding DB, secret, log Worker dan respons rangkaian di pelayar.
10. Commit dan push ke GitHub
Semak git status supaya tiada secret atau fail hasil build tersalah masuk. Kemudian jalankan git add ., git commit -m "Bina laman dan blog", dan git push -u origin main. Jika repo GitHub sudah mempunyai README yang berbeza, selaraskan sejarah dahulu; jangan paksa push tanpa memahami perubahan yang akan hilang. Bagi kerja seterusnya, ulang kitaran edit → build → semak → commit → push.
11. Sambung GitHub kepada Cloudflare Workers Builds
Di dashboard Cloudflare, buka Workers & Pages, cipta Worker atau pilih Worker yang sudah ada, kemudian buka Settings → Builds untuk sambungkan GitHub. Benarkan akses kepada repo yang betul. Tetapkan root directory /, production branch main, build command npm run build, dan deploy command npx wrangler deploy. Git integration akan menjalankan build apabila perubahan ditolak ke branch produksi; branch control menentukan branch mana yang benar-benar diterbitkan.
Push satu commit kecil untuk menguji sambungan. Lihat log build hingga selesai, kemudian buka alamat workers.dev. Jika halaman kosong, pastikan _site terhasil semasa build dan assets.directory sepadan. Jika build berjaya tetapi perubahan belum kelihatan, semak commit yang dideploy dan cache halaman; fail _headers dalam projek ini meminta HTML disemak semula.
12. Sambungkan domain sendiri
Jika domain anda sudah berada di Cloudflare, tambah Custom Domain pada Worker dalam dashboard dan ikut rekod DNS yang dicadangkan. Uji kedua-dua domain akar serta www mengikut pilihan anda. Kemas kini site.url di scripts/build-blog.mjs agar canonical URL, RSS dan sitemap menunjuk ke alamat sebenar. Semak pautan sosial serta metadata halaman. Tanpa domain sendiri pun, alamat workers.dev sudah cukup untuk memastikan pipeline bekerja.
13. Semak keseluruhan aliran seperti pembaca sebenar
Buka laman pada telefon dan komputer. Cari satu artikel melalui carian blog, tapis tag, pergi ke halaman kedua, buka artikel, dan periksa gambar. Semak /blog/feed.xml serta /sitemap.xml. Hantar borang ujian jika diaktifkan. Selepas itu buat perubahan kecil pada artikel, push ke main, dan lihat sama ada Cloudflare membina serta menerbitkannya tanpa deployment manual.
Apabila semuanya stabil, kerja harian menjadi sederhana: tulis dalam Markdown, gunakan gambar yang sesuai, build dan baca semula secara lokal, kemudian push. Jangan kejar jumlah artikel semata-mata; satu catatan yang menjawab masalah pembaca dengan jelas lebih berharga daripada sepuluh tajuk yang nampak penuh tetapi kosong isinya.