pkg: Executable Builder cho ứng dụng Node.js

pkg là gì?

pkg là một CLI của Vercel, gom một dự án Node.js — dependency, asset, và một bản Node binary đã vá — thành một file thực thi duy nhất, chạy được trên máy không cài Node.js. Mặc định pkg build cho cả Linux, macOS và Windows, quét các lệnh require() từ entry file để xác định cần đóng gói những gì. Theo README, pkg đã bị deprecated kể từ bản 5.8.1, và repo hiện đã được archive.

Các tính năng cốt lõi

• ✓Cross-compilation qua --targets: build cho node16-win-arm64, node18-linux và nhiều tổ hợp nền tảng khác trong một lệnh, mà không cần sở hữu phần cứng đó cho phần lớn trường hợp.
• ✓Snapshot filesystem: các file được đóng gói nằm dưới /snapshot/ bên trong binary, và __dirname hay require.main.filename tự trỏ về đó lúc runtime.
• ✓Compile sang V8 bytecode theo mặc định, có flag --no-bytecode để giữ nguyên mã nguồn JS khi cần build có hash lặp lại được (reproducible).
• ✓Đóng gói được native addon (file .node), pkg ghi addon ra một file tạm trên ổ đĩa lúc runtime vì Node không load native addon trực tiếp từ snapshot được.
• ✓Nén bằng Brotli hoặc GZip qua -C/--compress, README nói có thể giảm dung lượng filesystem nhúng bên trong tới 60%.
• ✓Baked sẵn các option runtime của V8/Node qua --options, nên các flag như expose-gc hay max-old-space-size được thiết lập sẵn bên trong file thực thi.
• ✓Có API dạng lập trình — const { exec } = require('pkg') — để đưa việc build vào script riêng thay vì gọi CLI trực tiếp.

Khi nào nên đóng gói Node.js thành file thực thi

• •Phát hành bản thương mại của ứng dụng mà không giao mã nguồn cho khách hàng.
• •Tạo bản demo hoặc dùng thử che giấu mã nguồn bên dưới.
• •Cross-compilation ra file thực thi cho nền tảng bạn không có máy để build.
• •Deploy dưới dạng một file duy nhất thay vì chạy npm install hàng trăm file trên server đích.
• •Dựng một installer hoặc self-extracting archive quanh asset của ứng dụng.
• •Test codebase với một bản Node.js mới mà không cần cài nó vào máy.

Cài đặt pkg

Cài pkg trên toàn hệ thống bằng npm install -g pkg, sau đó xác nhận đã có trong PATH bằng cách chạy pkg --help để xem toàn bộ flag. Không cần bước cấu hình riêng: chỉ cần trỏ pkg vào entry file (hoặc một package.json/thư mục chứa nó) và pkg tự quét require() để lo phần còn lại. Điều nên quyết định trước là danh sách --targets, vì nếu bỏ trống, pkg mặc định build cho linux, macos và win theo đúng phiên bản Node và kiến trúc máy bạn đang dùng.

Tạo file thực thi đầu tiên

Trỏ pkg thẳng vào entry file — pkg index.js — pkg sẽ tạo file thực thi cho cả Linux, macOS và Windows theo mặc định. Chạy pkg . thay vào đó thì pkg đọc trường bin trong package.json ở thư mục hiện tại. Cần một build cụ thể? pkg -t node16-win-arm64 index.js sẽ giới hạn vào đúng một target. Những gì pkg không tự quét được — lệnh require(variable) với tham số không phải chuỗi literal, hay asset không phải JS như view, ảnh — phải khai báo thủ công trong khối pkg của package.json, dùng glob pattern ở scripts và assets kèm outputPath tuỳ chọn. API cũng làm y hệt CLI: await exec(['app.js', '--target', 'host', '--output', 'app.exe']) trả về một promise, ghép được thẳng vào pipeline build của riêng bạn.

Lựa chọn thay thế cho pkg

Câu hỏi thường gặp

Vấn đề mà pkg giải quyết

Trước khi Node.js tự có tính năng single executable applications, muốn đưa một ứng dụng Node.js lên máy không cài Node thì hoặc phải bắt người dùng cài Node rồi chạy npm install, hoặc tự viết cơ chế đóng gói binary dựa trên snapshot và bytecode của V8. pkg gói toàn bộ bài toán đó — quét các lệnh require(), compile sang bytecode, nhúng một snapshot filesystem, cross-compilation sang nền tảng khác — vào một lệnh CLI duy nhất, đó là lý do các dự án ra đời trước Node 21 vẫn phụ thuộc vào pkg dù bản thân pkg đã ngừng phát triển.

Nên dùng — và không nên dùng

Dùng pkg nếu bạn đang bảo trì một dự án sẵn có đã phụ thuộc vào nó, phiên bản Node mục tiêu vẫn nằm trong danh sách pkg hỗ trợ, hoặc cần build bản demo/dùng thử mà không lộ mã nguồn. Bỏ qua pkg nếu bắt đầu dự án mới: Node 21+ đã có sẵn tính năng single executable applications, và vì pkg dừng lại ở bản 5.8.1 nên sẽ không có hỗ trợ cho phiên bản Node mới hơn hay bản vá nào tiếp theo.

Repo liên quan