Pipeline Azure đầu tiên: từ npm ci tới artifact zip, đọc từng dòng
Pipeline của dashboard Next.js chạy xanh. Tải artifact về, giải nén lên server Windows, chạy node server.js: trang chủ lên bình thường, nhưng tới chỗ đầu tiên đụng vào một package có module native (phần viết bằng C++, biên dịch thành file .node) thì app chết, báo không load được module. File .node có trong gói. Cái thiếu là mấy file .dll nằm cạnh nó.
Output standalone của Next.js (đã nói trong bài về Dockerfile) dò xem code dùng những file nào để gom vào gói. Nó thấy file .node, nhưng không đọc được bên trong file đó để biết nó cần thêm DLL nào của Windows. Nên bước đóng gói của pipeline phải tự bù chỗ đó.
Bài này đi qua từng khối của pipeline đó, khối nào làm gì, chỗ nào dễ sai, và có hai chi tiết mình chỉ phát hiện khi viết bài này.
Nói nhanh cho ai chưa dùng: Azure Pipelines là dịch vụ CI/CD của Azure DevOps. Bạn đặt một file azure-pipelines.yml trong repo, mỗi lần push code, một máy (gọi là agent) lấy code về và chạy các bước trong file đó.
Khối 1: khi nào pipeline chạy
trigger:
branches:
include:
- main
- feat/*
pr:
branches:
include:
- main
trigger là CI trigger: push lên main hoặc nhánh feat/... nào thì pipeline chạy.
Còn khối pr thì đây là chi tiết thứ nhất: repo của dashboard nằm trên Azure Repos, và với Azure Repos, khối pr trong YAML bị bỏ qua hoàn toàn. Nó chỉ có tác dụng với repo trên GitHub và Bitbucket Cloud. Muốn pipeline chạy để kiểm tra mỗi pull request vào main trên Azure Repos, bạn phải vào cài đặt nhánh, thêm một branch policy kiểu Build validation trỏ tới pipeline này. File YAML không báo lỗi gì, nên ai đọc cũng tưởng PR đã được kiểm.
Khối 2: chạy trên máy nào, với biến gì
pool:
vmImage: 'windows-latest'
variables:
NODE_VERSION: '24.x'
vmImage chọn một máy ảo do Microsoft cấp (gọi là Microsoft-hosted agent), mỗi lần chạy là một máy sạch, chạy xong thì bị xoá. Có ba lựa chọn chính: ubuntu-latest, windows-latest, macos-latest. App Next.js chạy được trên cả hai cái đầu. Pipeline này chọn Windows vì server đích là Windows, đóng gói trên cùng hệ điều hành thì đỡ bất ngờ với package native. Nếu server là Linux, chọn ubuntu-latest: thường khởi động nhanh hơn.
Khối 3: cài Node và package
steps:
- task: NodeTool@0
displayName: 'Cài Node.js $(NODE_VERSION)'
inputs:
versionSpec: '$(NODE_VERSION)'
- script: npm ci
displayName: 'Cài package (npm ci)'
task: là một bước đóng gói sẵn của Azure, script: là chạy lệnh shell. $(NODE_VERSION) lấy giá trị biến khai báo ở khối 2.
Hai gợi ý cho khối này:
NodeTool@0vẫn chạy, nhưng Microsoft đã có task mới hơn làUseNode@1. Viết pipeline mới thì dùng cái mới.- Mỗi lần chạy là một máy sạch, nên
npm citải lại toàn bộ package từ đầu. TaskCache@2giữ lại cache của npm giữa các lần chạy, khoá theopackage-lock.json:
variables:
npm_config_cache: $(Pipeline.Workspace)/.npm
steps:
- task: Cache@2
inputs:
# Lock file đổi thì khoá đổi, cache cũ không dùng nữa
key: 'npm | "$(Agent.OS)" | package-lock.json'
restoreKeys: |
npm | "$(Agent.OS)"
path: $(npm_config_cache)
displayName: 'Cache npm'
- script: npm ci
Khối 4: test rồi mới build
- script: npm test
displayName: 'Chạy test'
- powershell: |
$env:NEXT_OUTPUT_STANDALONE = "1"
npm run build
displayName: 'Build Next.js standalone'
Thứ tự này có chủ đích: test đỏ thì dừng luôn, không tốn vài phút build một bản sẽ không dùng. Biến NEXT_OUTPUT_STANDALONE bật output standalone đúng như trong Dockerfile ở bài 1, nên pipeline và Docker dùng chung một cách build.
Khối 5: đóng gói, và chỗ thiếu DLL
- powershell: |
node scripts/package-standalone.mjs "$(Build.ArtifactStagingDirectory)/app-deploy"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
displayName: 'Đóng gói runtime theo file tracing'
Script đóng gói làm ba việc mà .next/standalone không tự làm: copy .next/static và public (thiếu hai thư mục này thì trang mất CSS và ảnh), bù các file DLL nằm cạnh module native, và loại những file không được phép rời khỏi máy build. Bản thật dài hơn nhiều vì nó dựng lại cây package từ kết quả file tracing. Phần lõi, viết gọn lại:
// scripts/package-standalone.mjs (rút gọn)
import { cpSync, existsSync, readdirSync } from 'node:fs';
import { join, relative } from 'node:path';
const out = process.argv[2];
if (!out) { console.error('Thiếu thư mục đích'); process.exit(1); }
// Không bao giờ đóng gói file .env* hay thư mục dữ liệu cục bộ, kể cả khi file tracing kéo theo
const isPrivate = (p) => p.split(/[\\/]/).some((part) => part === '.data' || part.startsWith('.env'));
cpSync('.next/standalone', out, { recursive: true, filter: (src) => !isPrivate(src) });
// Standalone không tự gom hai thư mục này
cpSync('.next/static', join(out, '.next/static'), { recursive: true });
if (existsSync('public')) cpSync('public', join(out, 'public'), { recursive: true });
// File tracing thấy file .node nhưng không biết nó cần DLL nào của Windows.
// Với mỗi file .node đã vào gói, tìm thư mục gốc của nó trong node_modules của project
// và copy mọi .dll nằm cạnh nó sang cùng vị trí trong gói.
const packed = join(out, 'node_modules');
for (const entry of readdirSync(packed, { withFileTypes: true, recursive: true })) {
if (!entry.isFile() || !entry.name.endsWith('.node')) continue;
const rel = relative(packed, entry.parentPath); // ví dụ: some-native-pkg/build/Release
const sourceDir = join('node_modules', rel);
for (const dll of readdirSync(sourceDir).filter((f) => f.toLowerCase().endsWith('.dll'))) {
cpSync(join(sourceDir, dll), join(packed, rel, dll));
}
}
// Kiểm lại: thiếu file chính là dừng pipeline, không để artifact hỏng đi tiếp
for (const f of ['server.js', '.next/static']) {
if (!existsSync(join(out, f))) { console.error('Thiếu ' + f); process.exit(1); }
}
Hàm isPrivate đáng để ý không kém chuyện DLL: file tracing dò theo những gì code đọc, và nếu code đọc file .env lúc chạy thì file đó có thể bị kéo vào gói. Gói rời khỏi máy build mà mang theo .env thì ai tải được artifact là đọc được secret.
Dòng if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } là chi tiết thứ hai. Trong bước powershell, một lệnh ngoài (như node) thất bại không tự làm dừng script. Task PowerShell của Azure chỉ kiểm mã thoát của lệnh cuối cùng trong script. Nếu node lỗi ở giữa script mà sau nó còn lệnh khác chạy thành công, bước đó vẫn xanh. Script này chỉ có một lệnh nên dòng kiểm hơi thừa, nhưng mình giữ nó như một thói quen: thêm lệnh vào sau thì không ai phải nhớ chuyện này nữa.
Khối 6: nén và đưa artifact lên
- task: ArchiveFiles@2
displayName: 'Nén thành zip'
inputs:
rootFolderOrFile: '$(Build.ArtifactStagingDirectory)/app-deploy'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/app-deploy-$(Build.BuildId).zip'
- task: PublishPipelineArtifact@1
displayName: 'Publish artifact'
inputs:
targetPath: '$(Build.ArtifactStagingDirectory)/app-deploy-$(Build.BuildId).zip'
artifact: 'app-deploy'
Artifact là kết quả của pipeline được giữ lại sau khi máy agent bị xoá: bạn tải về từ trang kết quả, hoặc một pipeline deploy lấy nó để cài. includeRootFolder: false để giải nén ra là thấy ngay server.js, không phải chui thêm một tầng thư mục. Tên file có $(Build.BuildId) để mỗi lần chạy một tên khác nhau, không đè lẫn nhau khi tải về.
PublishPipelineArtifact@1 là task mới, nhanh hơn PublishBuildArtifacts@1 cũ. Hai task cho ra hai loại artifact khác nhau, nên một pipeline nên dùng thống nhất một loại, đừng trộn.
Toàn bộ pipeline
trigger:
branches:
include: [main, feat/*]
# PR vào main được kiểm bằng branch policy trên Azure Repos, không phải bằng khối pr
pool:
vmImage: 'windows-latest'
variables:
NODE_VERSION: '24.x'
npm_config_cache: $(Pipeline.Workspace)/.npm
steps:
- task: UseNode@1
inputs:
version: '$(NODE_VERSION)'
displayName: 'Cài Node.js'
- task: Cache@2
inputs:
key: 'npm | "$(Agent.OS)" | package-lock.json'
restoreKeys: |
npm | "$(Agent.OS)"
path: $(npm_config_cache)
displayName: 'Cache npm'
- script: npm ci
displayName: 'Cài package'
- script: npm test
displayName: 'Chạy test'
- powershell: |
$env:NEXT_OUTPUT_STANDALONE = "1"
npm run build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
displayName: 'Build Next.js standalone'
- powershell: |
node scripts/package-standalone.mjs "$(Build.ArtifactStagingDirectory)/app-deploy"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
displayName: 'Đóng gói runtime'
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.ArtifactStagingDirectory)/app-deploy'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/app-deploy-$(Build.BuildId).zip'
displayName: 'Nén zip'
- task: PublishPipelineArtifact@1
inputs:
targetPath: '$(Build.ArtifactStagingDirectory)/app-deploy-$(Build.BuildId).zip'
artifact: 'app-deploy'
displayName: 'Publish artifact'
Những thứ đáng kiểm trong pipeline của bạn
| Kiểm | Vì sao |
|---|---|
Repo trên Azure Repos mà có khối pr |
Khối đó không làm gì; cần branch policy |
| Bước PowerShell có nhiều lệnh ngoài | Lệnh lỗi ở giữa không làm bước đỏ |
npm install thay vì npm ci |
Build trên agent có thể khác lock file |
| Không có cache | Mỗi lần chạy tải lại toàn bộ package |
| Đóng gói không kiểm lại kết quả | Artifact thiếu file vẫn đi tiếp tới server |
Thử ngay: mở trang Branches của repo trên Azure DevOps, bấm vào main, xem mục Branch policies có Build validation không. Nếu không có, PR vào main đang được merge mà không ai chạy pipeline.
Bài sau trong series: đặt tên bản build theo version lấy từ git tag, chia stage, và gắn nút phê duyệt trước khi lên production. Pipeline đầu tiên của bạn hỏng ở bước nào? Comment kể mình nghe với.
P.S. Mấy lỗi pipeline kiểu "xanh mà artifact hỏng" mình hay mang tới skill intelligent-bug-fixer trong PrimeKit, bộ skill mình tự làm. Skill nhận một lỗi cụ thể (test đỏ, CI hỏng, giao diện vỡ), chẩn đoán, sửa đúng chỗ rồi kiểm lại, và tự điều chỉnh mức điều tra theo độ lớn của lỗi. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:intelligent-bug-fixer kèm log của lần chạy lỗi. Nó không vào được Azure DevOps của bạn, nên log phải do bạn đưa.
Tài liệu để đọc thêm
- YAML schema của Azure Pipelines, Microsoft Learn
- Trigger cho Azure Repos Git, mục PR triggers, Microsoft Learn
- Pipeline caching, Microsoft Learn
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Front End thực chiến: những bài toán UI mà tutorial không dạy: ngày giờ và giờ mùa hè, tầng dữ liệu theo hợp đồng API, chart, in ấn và accessibility, Outlook Add-in, E2E với Playwright.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved