คู่มือฉบับสมบูรณ์: การสร้างโปรแกรมเดสก์ท็อป .EXE จาก Electron และ GitHub Actions

📚 คู่มือและบันทึกขั้นตอนการพัฒนาโปรแกรม Electron App เป็นไฟล์ .EXE ผ่าน GitHub Actions

ผู้บันทึก/ผู้พัฒนา: ลุงแจ่ม อารมณ์ดี
วัตถุประสงค์: ใช้เป็นคู่มือมาตรฐาน (Standard Operating Procedure) สำหรับสร้างและแก้ไขปัญหาการคอมไพล์โปรแกรมเดสก์ท็อปจากศูนย์ (Clean Slate)

---

1. โครงสร้างพื้นฐานของโปรเจกต์ (Project Structure)

โปรเจกต์ประกอบด้วยไฟล์สำคัญหลักๆ ดังนี้:

• index.html: หน้าตาอินเทอร์เฟซและการทำงานของแอปพลิเคชัน (Frontend)
• main.js: ไฟล์ควบคุมกระบวนการหลักของระบบ Electron (Backend / Main Process)
• package.json: ไฟล์กำหนดค่า ติดตั้งไลบรารี และสคริปต์คำสั่งการทำงาน
• .github/workflows/build-exe.yml: ไฟล์ระบบอัตโนมัติ (GitHub Actions) สำหรับ Build ไฟล์ `.exe` บนคลาวด์

2. รายละเอียดโค้ดในแต่ละไฟล์หลัก

ก. ไฟล์ `main.js` (เวอร์ชันที่ถูกต้องสมบูรณ์)

const { app, BrowserWindow } = require('electron');
const path = require('path');

function createWindow() {
  const win = new BrowserWindow({
    width: 450,
    height: 850,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    },
    autoHideMenuBar: true,
    title: "TEXAS INTECH Audio Rack"
  });

  win.loadFile('index.html');
}

app.whenReady().then(() => {
  createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

// ⚠️ สำคัญ: ต้องใช้ app.quit() เท่านั้น ห้ามใช้ app.stop()
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

ข. ไฟล์ `package.json` (ตั้งค่าระบบและปิด Publish อัตโนมัติ)

{
  "name": "texas-intech-audio-rack",
  "version": "1.0.0",
  "description": "Pro 7-Layer Audio Rack Desktop App",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build": "electron-builder --win --x64"
  },
  "build": {
    "win": {
      "icon": "icon.ico"
    },
    "publish": null
  },
  "devDependencies": {
    "electron": "^28.0.0",
    "electron-builder": "^24.6.0"
  }
}

ค. ไฟล์ GitHub Actions Workflow (`.github/workflows/build-exe.yml`)

name: Build Desktop App (.exe)

on:
  push:
    branches: [ "main", "master" ]

jobs:
  build:
    runs-on: windows-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: 18

    - name: Install Dependencies
      run: npm install

    - name: Build Electron App
      run: npx electron-builder --win --x64

    - name: Upload Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: Windows-EXE-App
        path: dist/*.exe

---

3. บันทึกปัญหาที่พบทั้งหมดและแนวทางแก้ไข (Troubleshooting Log)

❌ ปัญหาที่ 1: JavaScript Error ใน Main Process (คำสั่ง `app.stop()`)

อาการ: เมื่อติดตั้งโปรแกรมลงในเครื่อง และกดปิดโปรแกรม จะมีหน้าต่าง Error เด้งขึ้นมาแจ้งว่า TypeError: app.stop is not a function[cite: 4]

สาเหตุ: ในไลบรารีของ Electron ไม่มีฟังก์ชันคำสั่งชื่อ app.stop()

วิธีแก้: เข้าไปแก้ไขในไฟล์ main.js เปลี่ยนจากคำสั่ง app.stop(); เป็น app.quit(); ให้ถูกต้อง

❌ ปัญหาที่ 2: GitHub Actions Build Fail ด้วย Exit Code 1 (Missing GitHub Token)

อาการ: ไปตรวจสอบในแท็บ Actions บน GitHub แล้วพบสถานะ Failure ขัดข้องที่ขั้นตอนการ Build พร้อมฟ้องว่า GitHub Personal Access Token is not set, neither programmatically, nor using env "GH_TOKEN"[cite: 2, 7]

สาเหตุ: electron-builder พยายามอัปโหลดไฟล์ขึ้น GitHub Releases โดยอัตโนมัติ แต่ไม่มีสิทธิ์ Token ยืนยันตัวตน

วิธีแก้: เพิ่มค่าการตั้งค่า "publish": null ไว้ภายในบล็อก "build" ของไฟล์ package.json เพื่อปิดการเผยแพร่อัตโนมัติและเก็บไฟล์ติดตั้งไว้ใน Local Artifacts ของ Actions แทน

❌ ปัญหาที่ 3: ติดตั้งทับไม่ได้ ฟ้องว่าโปรแกรมไม่สามารถปิดได้ (Cannot be closed)

อาการ: ตอนรันตัวติดตั้ง `.exe` ตัวใหม่ทับลงเครื่อง มีหน้าต่างแจ้งเตือนว่าโปรแกรมกำลังทำงานอยู่และไม่สามารถปิดได้อัตโนมัติ[cite: 6]

สาเหตุ: มีกระบวนการ (Process) ของแอปพลิเคชันเวอร์ชันเก่าค้างรันอยู่เบื้องหลังใน Windows

วิธีแก้: 1. กดปุ่ม Ctrl + Shift + Esc เพื่อเปิด Task Manager
2. กดขยายหน้าต่างด้วยปุ่ม More details
3. ค้นหาชื่อโปรแกรมหรือ Electron แล้วคลิกขวาเลือก End task เพื่อบังคับปิดให้สนิท
4. ดับเบิลคลิกไฟล์ติดตั้งใหม่อีกครั้ง

---

4. วิธีการใส่ไอคอนรูปเฉพาะตัวให้กับแอปพลิเคชัน (.ICO)

1. เตรียมไฟล์รูปภาพแปลงเป็นนามสกุล .ico ขนาดแนะนำ 256x256 พิกเซล และตั้งชื่อไฟล์ว่า icon.ico
2. อัปโหลดไฟล์ icon.ico ขึ้นไปไว้ที่หน้าหลักของโปรเจกต์บน GitHub (ผ่านปุ่ม Add file -> Upload files)
3. กำหนดค่าเชื่อมโยงไอคอนในไฟล์ package.json ภายใต้หมวด "build" ดังนี้:

   "build": {
     "win": {
       "icon": "icon.ico"
     },
     "publish": null
   }

4. ทำการ Commit บันทึกไฟล์ และรอ GitHub Actions ทำการคอมไพล์โปรแกรมใหม่ เพียงเท่านี้ไฟล์ติดตั้ง `.exe` และไอคอนแอปพลิเคชันก็จะเปลี่ยนเป็นรูปที่คุณต้องการทันที

💡 ข้อสังเกต: หากไม่มีการเปลี่ยนแปลงไฟล์รูปภาพ icon.ico ในโปรเจกต์ ระบบจะดึงไอคอนเดิมมาใช้งานอย่างสม่ำเสมอทุกครั้งที่มีการ Build ใหม่ครับ