ShellCheck: 39,456 GitHub Stars — Hướng Dẫn Cài Đặt và Tích Hợp CI/CD cho Phân Tích Shell Script 2026

{{< resource-info >}}

ShellCheck là tiêu chuẩn thực tế để phát hiện bug trong shell script trước khi triển khai production. Với 39,456+ sao GitHub và cộng đồng open-source tích cực, đây là công cụ phân tích tĩnh được áp dụng rộng rãi nhất cho các script bash, sh, dash và ksh. Hướng dẫn này đi qua cài đặt ShellCheck, tích hợp với editor và CI/CD pipeline, cũng như các phương pháp tăng cường production.

Giới thiệu #

Shell script điều khiển các pipeline triển khai, tự động hóa hệ thống, và quản lý cơ sở hạ tầng. Một biến không được quote hoặc mã return không được kiểm tra có thể làm hỏng dữ liệu, lộ credential, hoặc làm sập server production. Hậu quả của Heartbleed 2014 và vô số sự cố CI/CD đều bắt nguồn từ các bug shell script mà phân tích tĩnh có thể phát hiện.

ShellCheck, được Vidar Holen tạo ra năm 2012, lấp đầy khoảng trống này. Nó phân tích shell script mà không cần thực thi, nhận diện lỗi cú pháp, các cạm bẫy ngữ nghĩa, vấn đề portability và lỗ hổng bảo mật. Với hơn 280 quy tắc kiểm tra tích hợp (mỗi quy tắc có mã SC riêng), ShellCheck phát hiện từ lỗi cơ bản của ngườI mới đến các trường hợp edge case tinh vi khiến cả developer dày dặn kinh nghiệm cũng mắc phải.

Hướng dẫn này bao gồm shellcheck tutorial và hướng dẫn cài đặt shellcheck đầy đủ: cài đặt đa nền tảng, tích hợp editor, sử dụng shellcheck docker, cấu hình GitHub Actions, tăng cường production và bash linting. Dù bạn đang lint một script triển khai đơn lẻ hay thiết lập quality gate cho cả monorepo, các cấu hình dưới đây sẵn sàng để sao chép, điều chỉnh và triển khai.

ShellCheck là gì? #

ShellCheck là công cụ phân tích tĩnh (“linter”) cho shell script. Nó đọc mã nguồn bash/sh/dash/ksh, xây dựng abstract syntax tree (AST), và áp dụng các quy tắc ngữ nghĩa để phát hiện bug, anti-pattern và vi phạm style — tất cả mà không cần thực thi script.

Dự án được viết bằng Haskell (96.4% codebase), phân phối theo giấy phép GPL-3.0, được Vidar Holen bảo trì cùng 166+ contributor. Phiên bản ổn định v0.11.0 được phát hành ngày 4 tháng 8 năm 2025.

Khả năng chính #

• Xác thực cú pháp: Bắt cấu trúc sai trước runtime
• Phân tích ngữ nghĩa: Phát hiện biến không quote, code unreachable, và exit code bị che
• Kiểm tra portability: Cảnh báo bashism trong script /bin/sh cần tuân thủ POSIX
• Kiểm toán bảo mật: Nhận diện vector command injection và pattern eval không an toàn
• Thực thi style: Đề xuất cấu trúc hiện đại thay thế cú pháp deprecated

ShellCheck hoạt động như thế nào #

ShellCheck vận hành như một pipeline phân tích đa tầng. Hiểu kiến trúc này giúp tối ưu hiệu năng và diễn giải kết quả.

Tổng quan kiến trúc #

Source Script → Lexer → Parser (AST) → Analyzer → Reporter
                     ↓           ↓            ↓
                 Tokens    Syntax Tree    SC-Warnings

1. Lexer: Token hóa script thành identifiers, keywords, operators và literals
2. Parser: Xây dựng AST từ token stream, xử lý các đặc thù grammar của shell
3. Analyzer: Duyệt AST và áp dụng 280+ quy tắc, mỗi quy tắc ánh xạ đến mã lỗi SC
4. Reporter: Định dạng kết quả thành terminal output, JSON, CheckStyle XML, GCC warnings, hoặc SARIF

Mức độ nghiêm trọng #

Mỗi phát hiện của ShellCheck mang một trong bốn mức độ nghiêm trọng:

Các nhóm kiểm tra chính #

• SC1xxx: Vấn đề cú pháp và parsing (ví dụ: SC1007 — dấu cách sau =)
• SC2xxx: Cảnh báo ngữ nghĩa và portability (ví dụ: SC2086 — biến không quote)
• SC3xxx: Ghi chú tương thích bash/dash/ksh
• SC4xxx: Kiểm tra tùy chọn và quy tắc thử nghiệm

Cài đặt và thiết lập #

ShellCheck có mặt trên mọi nền tảng chính. Cài đặt mất dưới hai phút.

Linux (APT / Debian / Ubuntu) #

# Cập nhật package index
sudo apt update

# Cài đặt ShellCheck
sudo apt install -y shellcheck

# Kiểm tra phiên bản
shellcheck --version
# ShellCheck - shell script analysis tool
# version: 0.11.0
# license: GNU General Public License, version 3
# website: https://www.shellcheck.net

Linux (DNF / Fedora / RHEL) #

# Cài qua DNF
sudo dnf install -y shellcheck

# Kiểm tra phiên bản
shellcheck --version

macOS (Homebrew) #

# Cài qua Homebrew
brew install shellcheck

# Kiểm tra phiên bản
shellcheck --version

Windows (qua Chocolatey) #

# Cài qua Chocolatey (cửa sổ admin)
choco install shellcheck

# Kiểm tra phiên bản
shellcheck --version

Docker (Độc lập nền tảng) #

# Chạy ShellCheck qua Docker không cần cài đặt local
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
  /mnt/deploy.sh

# Kiểm tra tất cả script trong thư mục hiện tại
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
  /mnt/*.sh

# Khóa phiên bản cụ thể cho CI build tái lập
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:v0.11.0 \
  /mnt/deploy.sh

Build từ source (Haskell Stack) #

# Clone repository
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck

# Build với Stack
stack install

# Hoặc build với Cabal
cabal update
cabal install

Pre-commit hook #

# Thêm vào .pre-commit-config.yaml
repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.11.0
    hooks:
      - id: shellcheck
        args: ["--severity=warning"]

Tích hợp editor #

ShellCheck phát huy sức mạnh khi phản hồi xuất hiện real-time khi bạn gõ. Mọi editor chính đều có plugin ShellCheck.

VS Code #

Cài đặt extension ShellCheck của Timon Wong (marketplace ID: timonwong.shellcheck).

// settings.json
{
  "shellcheck.executablePath": "shellcheck",
  "shellcheck.exclude": ["SC1090", "SC1091"],
  "shellcheck.severity": "warning",
  "shellcheck.run": "onType"
}

Vim / Neovim #

Sử dụng ALE (Asynchronous Lint Engine):

" .vimrc hoặc init.vim
let g:ale_linters = {
\   'sh': ['shellcheck'],
\}

" Chạy khi lưu và khi đang gõ
let g:ale_lint_on_save = 1
let g:ale_lint_on_text_changed = 'always'

Sử dụng native LSP trong Neovim:

-- init.lua (nvim-lspconfig)
require('lspconfig').bashls.setup {
  settings = {
    bashIde = {
      shellcheckPath = "shellcheck"
    }
  }
}

Emacs #

;; init.el với Flycheck
(add-hook 'sh-mode-hook #'flycheck-mode)
(setq flycheck-shellcheck-severity "warning")

Sublime Text #

Cài đặt qua Package Control: SublimeLinter-shellcheck.

// SublimeLinter.sublime-settings
{
  "linters": {
    "shellcheck": {
      "executable": "shellcheck",
      "args": ["--severity=warning"]
    }
  }
}

Tích hợp CI/CD #

Chạy ShellCheck trong CI ngăn chặn script có bug được merge. Dưới đây là cấu hình sẵn sàng sử dụng cho GitHub Actions, GitLab CI, và Jenkins.

GitHub Actions #

# .github/workflows/shellcheck.yml
name: ShellCheck

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Chạy ShellCheck
        uses: ludeeus/action-shellcheck@master
        env:
          SEVERITY: warning
        with:
          ignore_paths: >-
            ./vendor
            ./third_party

Cách thiết lập thủ công với phiên bản cố định:

# .github/workflows/shellcheck-manual.yml
name: ShellCheck Manual

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cài đặt ShellCheck
        run: |
          wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz" | tar -xJf -
          sudo cp "shellcheck-v0.11.0/shellcheck" /usr/local/bin/

      - name: Lint tất cả shell script
        run: |
          find . -name "*.sh" -type f -print0 | \
            xargs -0 shellcheck --severity=warning --format=tty

GitLab CI #

# .gitlab-ci.yml
stages:
  - lint

shellcheck:
  stage: lint
  image: koalaman/shellcheck-alpine:stable
  script:
    - find . -name "*.sh" -type f -exec shellcheck --severity=warning {} +
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Jenkins #

// Jenkinsfile
pipeline {
    agent any

    stages {
        stage('ShellCheck') {
            steps {
                sh '''
                    #!/bin/bash
                    set -euo pipefail

                    if ! command -v shellcheck &> /dev/null; then
                        echo "Đang cài đặt ShellCheck..."
                        apt-get update && apt-get install -y shellcheck
                    fi

                    find . -name "*.sh" -type f -print0 | \
                        xargs -0 shellcheck --severity=warning
                '''
            }
        }
    }

    post {
        failure {
            echo "ShellCheck phát hiện vấn đề. Vui lòng xem build log."
        }
    }
}

CircleCI #

# .circleci/config.yml
version: 2.1
orbs:
  shellcheck: circleci/shellcheck@3.2.0

workflows:
  lint:
    jobs:
      - shellcheck/check:
          severity: "warning"
          exclude: "SC1090,SC1091"

Cấu hình và quản lý quy tắc #

ShellCheck cung cấp nhiều cơ chế kiểm soát quy tắc chạy và cách báo cáo.

Chỉ thị inline #

#!/bin/bash
# shellcheck disable=SC2086
echo $UNQUOTED_VAR  # Dòng này tắt SC2086

# shellcheck disable=SC2034
UNUSED_VAR="biến này được gán nhưng không dùng"

# Bật lại sau khối code
# shellcheck enable=SC2086
echo "$PROPERLY_QUOTED"

File cấu hình (.shellcheckrc) #

# .shellcheckrc — cấu hình cấp project
# Đặt ở repo root hoặc $HOME/.shellcheckrc

# Thiết lập shell dialect cho script không có shebang
shell=bash

# Loại bỏ kiểm tra cụ thể toàn cục
disable=SC1090,SC1091,SC2155

# Thiết lập mức độ nghiêm trọng tối thiểu
severity=warning

# Bật kiểm tra tùy chọn
enable=require-variable-braces,check-set-e-suppressed

# Chỉ định external sources
external-sources=true

Lọc mức độ nghiêm trọng #

# Chỉ báo error và warning (bỏ info/style)
shellcheck --severity=warning script.sh

# Chỉ báo error
shellcheck --severity=error script.sh

Định dạng output #

# Terminal output mặc định
shellcheck --format=tty script.sh

# JSON để xử lý programmatic
shellcheck --format=json script.sh > shellcheck-report.json

# CheckStyle XML (tương thích Jenkins, GitLab)
shellcheck --format=checkstyle script.sh > shellcheck.xml

# GCC-compatible (tích hợp editor chung)
shellcheck --format=gcc script.sh

# SARIF cho GitHub Security tab
shellcheck --format=sarif script.sh > shellcheck.sarif

Benchmark và use case thực tế #

ShellCheck được áp dụng từ developer cá nhân đến enterprise CI/CD pipeline.

Benchmark hiệu năng #

Test trên CI runner tiêu chuẩn 2024 (Ubuntu 24.04, 2 vCPU, 4 GB RAM):

Mức độ áp dụng thực tế #

• GitHub Actions: Action chính thức ludeeus/action-shellcheck chạy 500K+ lần/tháng
• Homebrew: Lint tất cả 5,000+ formula script bằng ShellCheck
• Google Shell Style Guide: Khuyến nghị ShellCheck cho mọi shell script
• NixOS: Sử dụng ShellCheck trong package build pipeline
• Debian / Ubuntu: Được đóng gói và bảo trì trong official repositories

Các nhóm bug phát hiện (Phân tích mẫu 1,000 script open-source) #

Sử dụng nâng cao và tăng cường production #

Cho team chạy ShellCheck ở quy mô lớn, các pattern này cải thiện độ tin cậy.

Phân tích hàng loạt đa script #

#!/bin/bash
set -euo pipefail

SEVERITY="warning"
SCRIPT_DIRS=("scripts/" "bin/" "deploy/")
EXCLUDES=()

# Xây dựng danh sách loại trừ
for code in SC1090 SC1091 SC2155; do
    EXCLUDES+=("-e" "$code")
done

# Tìm và lint tất cả shell script
find "${SCRIPT_DIRS[@]}" -name "*.sh" -type f -print0 | \
    xargs -0 shellcheck --severity="$SEVERITY" "${EXCLUDES[@]}"

echo "Tất cả script đã pass ShellCheck ở mức: $SEVERITY"

Upload SARIF lên GitHub Security Dashboard #

# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Chạy ShellCheck SARIF
        run: |
          find . -name "*.sh" -type f -print0 | \
            xargs -0 shellcheck --format=sarif > shellcheck.sarif || true

      - name: Upload lên GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: shellcheck.sarif

Stage linting trong Dockerfile #

# Dockerfile
FROM koalaman/shellcheck:stable AS lint
WORKDIR /scripts
COPY . .
RUN find . -name "*.sh" -exec shellcheck --severity=warning {} +

FROM alpine:3.20 AS runtime
COPY --from=lint /scripts/deploy.sh /usr/local/bin/
ENTRYPOINT ["/usr/local/bin/deploy.sh"]

Theo dõi ShellCheck trong CI #

Theo dõi số lượng lỗi ShellCheck như một team metric:

#!/bin/bash
# ci-metrics.sh — theo dõi số warning shellcheck theo thờI gian

WARNINGS=$(find . -name "*.sh" -exec shellcheck --severity=warning --format=json {} + | \
    jq '. | length')

echo "shellcheck_warnings $WARNINGS" >> metrics.txt

So sánh với các công cụ thay thế #

Khi nào chọn công cụ nào #

• ShellCheck: Phân tích chất lượng và bảo mật shell script đa năng. Lựa chọn mặc định.
• bash -n: Xác thực cú pháp bash nhanh khi không có lựa chọn khác.
• shfmt: Định dạng code và chuẩn hóa style. Bổ sung cho ShellCheck (không thay thế).
• checkbashisms: Kiểm tra portability cho Debian. Dùng khi đóng gói Debian/Ubuntu.

Hạn chế và đánh giá khách quan #

ShellCheck không phải là giải pháp vạn năng. Hiểu rõ giới hạn giúp tránh tự tin thái quá.

Những gì ShellCheck KHÔNG phát hiện #

• Lỗi logic runtime: Không thể xác định lệnh curl của bạn có trỏ đúng endpoint không
• Bug business logic: Nó xác thực cú pháp, không xác thực script backup có sao lưu đúng thư mục không
• Vấn đề hiệu năng: Vòng lặp vô hạn với cú pháp hợp lệ sẽ pass sạch sẽ
• Phân tích Turing-complete: Một số hành vi động (ví dụ: eval "$DYNAMIC_CMD") vốn không thể phân tích

Khoảng trống nền tảng và môi trường #

• ShellCheck giả định các tiện ích Unix tiêu chuẩn. Script cho hệ thống embedded hoặc busybox có thể báo false positive
• Một số quy tắc SC mang tính chủ quan. Team nên xem xét và tùy chỉnh .shellcheckrc thay vì áp dụng mù quáng mọi gợi ý
• Không hỗ trợ script Windows native (PowerShell, CMD)

Cân nhắc build và dependency #

• Runtime Haskell thêm ~30 MB vào Docker image khi build từ source
• Binary pre-built (cách khuyến nghị) không có runtime dependency
• CI pipeline nên khóa phiên bản cụ thể để tránh build break từ các kiểm tra mới trong release

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

ShellCheck hỗ trợ những shell nào? #

ShellCheck hỗ trợ bash, dash, sh, ksh và busybox sh. Không hỗ trợ PowerShell, zsh (một phần) và fish. Chỉ định shell đích bằng --shell bash|sh|dash|ksh hoặc qua shebang trong script.

Làm sao tắt một cảnh báo ShellCheck cụ thể? #

Dùng chỉ thị inline: # shellcheck disable=SC2086 ở dòng trước cảnh báo. Để tắt toàn project, thêm disable=SC2086 vào .shellcheckrc. Mỗi kiểm tra có trang wiki tại https://www.shellcheck.net/wiki/SC2086 giải thích lý do.

ShellCheck có tự động sửa script không? #

Giao diện web tại shellcheck.net cung cấp gợi ý tự động sửa cho nhiều vấn đề thường gặp. Công cụ CLI hiển thị các bản sửa đề xuất trong output nhưng không sửa file trực tiếp. Một số công cụ third-party bọc ShellCheck để áp dụng sửa tự động.

Làm sao tích hợp ShellCheck với pre-commit hook? #

Thêm hook pre-commit chính thức từ https://github.com/koalaman/shellcheck-precommit vào .pre-commit-config.yaml. Đặt args: ["--severity=warning"] để chặn commit có warning, hoặc args: ["--severity=error"] để chỉ chặn error.

ShellCheck có phù hợp kiểm toán bảo mật không? #

ShellCheck nhận diện các pattern bảo mật phổ biến như command injection (SC2096), sử dụng eval không an toàn, và biến không quote có thể mở rộng độc hại. Tuy nhiên, nó không thay thế scanner bảo mật chuyên dụng. Kết hợp với Semgrep hoặc GitHub CodeQL để có coverage bảo mật toàn diện.

Tại sao ShellCheck gắn cờ code chạy bình thường? #

Nhiều cảnh báo ShellCheck đề cập các trường hợp “hiện tại chạy được, sau này sẽ hỏng”. Biến không quote có thể hoạt động với tên file không có dấu cách nhưng sẽ fail với input có dấu cách hoặc ký tự glob. Các cảnh báo ngăn bug tiềm ẩn hiện ra trong production.

Làm sao chạy ShellCheck trong container Docker? #

Dùng image chính thức: docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable /mnt/script.sh. Khóa vào v0.11.0 hoặc phiên bản cụ thể khác cho CI build tái lập. Image dựa trên Alpine Linux, khoảng 15 MB.

Kết luận #

ShellCheck là công cụ phân tích tĩnh shell script trưởng thành và được áp dụng rộng rãi nhất. Với 39,456+ sao GitHub, tích hợp CI/CD toàn diện và hỗ trợ mọi editor chính, ShellCheck xứng đáng có mặt trong toolchain của mọi developer. Bắt đầu với Docker one-liner để có phản hồi tức thì, thêm cấu hình project .shellcheckrc cho tính nhất quán team, và kết nối GitHub Actions để bắt bug trước khi merge.

Các hành động cho team bạn:

1. Chạy shellcheck trên top 5 script triển khai quan trọng nhất ngay hôm nay
2. Cài extension VS Code hoặc tích hợp Vim ALE để có phản hồi real-time
3. Tạo .shellcheckrc ở repo root với các quy tắc project-specific
4. Thiết lập workflow GitHub Actions để chặn merge có warning

Tham gia nhóm Telegram dibi8 để thảo luận về developer tools, best practice CI/CD, và automation DevOps.

Hosting Và Hạ Tầng Được Đề Xuất #

Trước khi triển khai các công cụ trên vào production, bạn cần hạ tầng vững chắc. Hai lựa chọn dibi8 đang dùng:

• DigitalOcean — Credit miễn phí $200 trong 60 ngày, 14+ khu vực toàn cầu. Lựa chọn mặc định cho dev chạy AI tools open source.
• HTStack — VPS Hong Kong, độ trễ thấp khi truy cập từ Trung Quốc. Cùng IDC đang host dibi8.com.

Liên kết tiếp thị — không tăng chi phí của bạn, giúp dibi8.com hoạt động.

Nguồn và tài liệu tham khảo #

• ShellCheck Website Chính thức
• ShellCheck GitHub Repository
• ShellCheck Wiki — Tất cả mã kiểm tra
• ShellCheck v0.11.0 Release Notes
• ShellCheck Pre-commit Hook
• ludeeus/action-shellcheck — GitHub Action
• Google Shell Style Guide
• shfmt — Shell Formatter
• checkbashisms — Debian Devscripts
• POSIX.1-2017 Shell Command Language