Thiết lập script xây dựng với pkg trong 3 phút (kèm 5 ví dụ thực tế)

Bạn vẫn đang gặp khó khăn khi đóng gói dự án Node.js? Bài viết này cung cấp các mẫu script xây dựng pkg có thể sao chép và sử dụng ngay, hoàn thành thiết lập trong 3 phút, giải quyết vấn đề triển khai đa nền tảng. Sau khi đọc xong, bạn sẽ có được:

• Mẫu cấu hình package.json scripts tiêu chuẩn
• 5 tình huống thực tế phổ biến
• Thực hành tốt nhất khi đóng gói tài nguyên tĩnh
• Mẹo gỡ lỗi và kiểm thử

pkg là gì (công cụ đóng gói)

pkg là một công cụ có khả năng đóng gói dự án Node.js thành tệp thực thi (Executable File), hỗ trợ ba nền tảng lớn: Windows, macOS và Linux. Với cấu hình đơn giản, bạn có thể nói lời tạm biệt với nỗi đau triển khai "phải cài đặt môi trường Node", đặc biệt phù hợp cho việc phân phối ứng dụng độc lập.

Điểm nhập mã nguồn cốt lõi: lib/bin.ts

Mẫu cấu hình cơ bản

Dưới đây là mẫu cấu hình cơ bản phù hợp với hầu hết các dự án, chỉ cần sao chép vào package.json của bạn:

{
  "scripts": {
    "pkg:win": "pkg . --targets node18-win-x64 --output dist/app-win.exe",
    "pkg:mac": "pkg . --targets node18-macos-x64 --output dist/app-mac",
    "pkg:linux": "pkg . --targets node18-linux-x64 --output dist/app-linux",
    "pkg:all": "npm run pkg:win && npm run pkg:mac && npm run pkg:linux",
    "pkg:clean": "rimraf dist/*"
  },
  "pkg": {
    "assets": ["views/**/*", "public/**/*"],
    "targets": ["node18-win-x64", "node18-macos-x64", "node18-linux-x64"],
    "outputPath": "dist"
  }
}

Ví dụ tình huống thực tế

1. Đóng gói ứng dụng Express

Lấy dự án Express trong thư mục examples làm ví dụ, cần xử lý đặc biệt tệp view và tài nguyên tĩnh:

Cấu hình package.json trong examples/express:

{
  "pkg": {
    "assets": ["views/**/*"],
    "targets": ["node18"]
  }
}

Tệp điểm nhập tương ứng examples/express/index.js cần sử dụng đường dẫn chính xác:

// Phải sử dụng __dirname để đảm bảo tài nguyên có thể truy cập sau khi đóng gói
app.use('/', express.static(__dirname + '/views'));
app.get('/', function (req, res) {
  res.sendFile(__dirname + '/views/index.html');
});

2. Xây dựng song song đa nền tảng

Cấu hình lệnh xây dựng song song trong package.json tại thư mục gốc:

"scripts": {
  "pkg:parallel": "npm-run-all --parallel pkg:win pkg:mac pkg:linux"
}

Cần cài đặt phụ thuộc thực thi song song trước: npm install npm-run-all --save-dev

3. Dự án chứa module gốc

Đối với các dự án chứa module gốc như bcrypt, cần chỉ định phiên bản Node trong package.json:

"pkg": {
  "targets": ["node18-win-x64"],
  "scripts": "build.js",
  "assets": "node_modules/bcrypt/**/*"
}

Logic xử lý module gốc liên quan: lib/fabricator.ts

4. Tệp thực thi tối ưu hóa kích thước

Thực hiện đóng gói với kích thước tối thiểu thông qua nén và cắt gọt:

"scripts": {
  "pkg:min": "pkg . --targets node18-linux-x64 --compress GZip --output dist/app-min"
}

Triển khai thuật toán nén: lib/compress_type.ts

5. Quy trình đóng gói theo hướng kiểm thử

Tích hợp kiểm thử để đảm bảo chất lượng đóng gói, tham khảo script kiểm thử trong package.json tại thư mục gốc:

"scripts": {
  "test:pkg": "npm run build && pkg . && ./dist/app-linux --test",
  "ci": "npm run lint && npm test && npm run test:pkg"
}

Bộ kiểm thử hoàn chỉnh: test/test-50-package-json/

Giải quyết các vấn đề thường gặp

Tài nguyên tĩnh không tìm thấy

Đảm bảo:

1. Cấu hình assets chính xác: "assets": ["views/**/*"]
2. Sử dụng path.join(__dirname, 'views') trong code thay vì đường dẫn tương đối
3. Kiểm tra logic duyệt tài nguyên trong lib/walker.ts

Lỗi khi chạy sau đóng gói

1. Kiểm tra tính tương thích phiên bản Node.js, tham khảo test/test-50-package-json-6/
2. Sử dụng chế độ pkg --debug để tạo thông tin gỡ lỗi
3. Xác minh tất cả phụ thuộc đã được bao gồm, có thể tham khảo định nghĩa module trong dictionary/

Tài nguyên dự án

• Tài liệu chính thức: README.md
• Thư viện ví dụ cấu hình: examples/
• Bộ test: test/
• Module cốt lõi: lib/

Thông qua các mẫu và ví dụ trên, bạn có thể nhanh chóng triển khai đóng gói đa nền tảng cho dự án Node.js. Để biết thêm cấu hình nâng cao, hãy tham khảo mã nguồn dự án hoặc gửi issue để được hỗ trợ.