Python Click 命令列工具開發完整教學：從零打造專業 CLI 應用程式

說實話，我第一次用 Python 寫命令列工具的時候，是用內建的 argparse。那段經歷只能用「折磨」來形容——光是定義幾個參數就要寫一堆樣板程式碼，子指令的設定更是讓人頭痛到想翻桌。直到我遇見了 Click，才終於體會到什麼叫做「優雅地寫 CLI」。

Click 是由 Flask 的作者 Armin Ronacher 開發的命令列框架，名字本身就是 "Command Line Interface Creation Kit" 的縮寫。它用 Python 的裝飾器語法來定義命令列介面，寫起來不只簡潔，而且直覺到你幾乎不需要查文件就能上手。如果你對裝飾器還不太熟悉，建議先看看這篇 Python 裝飾器 Decorator 教學，會幫助你更快理解 Click 的設計理念。

為什麼選擇 Click 而非 argparse

我知道你可能會想：Python 內建就有 argparse 了，幹嘛還要裝第三方套件？這個問題我以前也問過自己，但用過 Click 之後就再也回不去了。讓我用一個簡單的例子來說明差異。

假設你要寫一個接受名字和次數的打招呼工具。用 argparse 大概會長這樣：

import argparse

parser = argparse.ArgumentParser(description='打招呼工具')
parser.add_argument('--name', required=True, help='你的名字')
parser.add_argument('--count', default=1, type=int, help='重複次數')
args = parser.parse_args()

for _ in range(args.count):
    print(f'哈囉，{args.name}！')

同樣的功能用 Click 來寫：

import click

@click.command()
@click.option('--name', required=True, help='你的名字')
@click.option('--count', default=1, help='重複次數')
def greet(name, count):
    """打招呼工具"""
    for _ in range(count):
        click.echo(f'哈囉，{name}！')

if __name__ == '__main__':
    greet()

看起來差不多？但等你要加子指令、參數驗證、互動式輸入的時候，Click 的優勢就會一目了然。argparse 的程式碼會急遽膨脹，而 Click 始終保持簡潔可讀。

Click 還有幾個關鍵優勢：自動生成的 help 訊息更漂亮、原生支援檔案處理、跨平台的 Unicode 支援，以及完善的測試工具。這些在 argparse 裡要嘛不支援，要嘛得自己硬幹。

安裝非常簡單，推薦使用現代化的套件管理工具，可以參考 Python uv 套件管理器教學 來設定你的開發環境：

pip install click

Click 基礎：@click.command 與 @click.option

Click 的核心概念超級簡單：用 @click.command() 裝飾器把一個普通函式變成命令列工具，用 @click.option() 定義選項參數，用 @click.argument() 定義位置參數。

先來搞清楚 option 和 argument 的差別。Option 是帶有旗標的可選參數，像 --name Alice；Argument 則是按位置傳入的必要參數，像 mycommand input.txt。一般來說，option 用在可選或有預設值的東西，argument 用在必須提供的核心輸入。

import click

@click.command()
@click.argument('filename')
@click.option('--output', '-o', default='result.txt', help='輸出檔案名稱')
@click.option('--verbose', '-v', is_flag=True, help='顯示詳細資訊')
def process(filename, output, verbose):
    """處理指定的檔案"""
    if verbose:
        click.echo(f'正在處理 {filename}...')
    click.echo(f'結果將輸出到 {output}')

if __name__ == '__main__':
    process()

注意幾個重點：option 可以設定短名稱（像 -v），可以用 is_flag=True 做布林旗標，也可以設定 default 預設值。Click 會自動把參數名稱轉成函式參數，所以 --output 就直接對應到 output 參數。

另外一個實用的功能是 multiple=True，讓同一個選項可以傳入多次：

@click.command()
@click.option('--tag', '-t', multiple=True, help='標籤（可多個）')
def tag_file(tag):
    for t in tag:
        click.echo(f'新增標籤：{t}')

執行 tag-file -t python -t cli -t tutorial 就會依序印出三個標籤。這在 argparse 裡要用 nargs 搞半天的功能，Click 一個參數就解決了。

參數類型與驗證

Click 內建了豐富的參數類型系統，遠比 argparse 的 type 參數來得強大。最常用的幾個：

click.Choice 限制選項只能從指定清單中選擇：

@click.option('--format', type=click.Choice(['json', 'csv', 'xml'], case_sensitive=False))
def export(format):
    click.echo(f'匯出為 {format} 格式')

click.Path 驗證檔案或目錄路徑是否存在：

@click.option('--config', type=click.Path(exists=True, readable=True, resolve_path=True))
def load(config):
    click.echo(f'載入設定檔：{config}')

click.Path 可以設定 exists=True 確保檔案存在、dir_okay=False 限制只接受檔案、resolve_path=True 自動轉成絕對路徑。這些在處理檔案操作時非常好用，不用再自己寫一堆 os.path.exists() 驗證。

click.IntRange 和 click.FloatRange 限制數值範圍：

@click.option('--port', type=click.IntRange(1024, 65535), default=8080)
def serve(port):
    click.echo(f'伺服器啟動在 port {port}')

如果你有特殊需求，也可以自訂參數型別。只要繼承 click.ParamType 並實作 convert 方法就好：

class DateType(click.ParamType):
    name = 'date'

    def convert(self, value, param, ctx):
        try:
            from datetime import datetime
            return datetime.strptime(value, '%Y-%m-%d').date()
        except ValueError:
            self.fail(f'{value} 不是有效的日期格式，請使用 YYYY-MM-DD', param, ctx)

DATE = DateType()

@click.option('--since', type=DATE, help='開始日期 (YYYY-MM-DD)')
def report(since):
    click.echo(f'產生自 {since} 以來的報告')

子指令與 Group 設計

當你的 CLI 工具功能變多，就需要子指令來組織結構。想想 git 有 git commit、git push、git pull——這就是子指令的經典範例。Click 用 @click.group() 來實現，簡單到不行。

@click.group()
@click.option('--debug/--no-debug', default=False)
@click.pass_context
def cli(ctx, debug):
    """我的超強 CLI 工具"""
    ctx.ensure_object(dict)
    ctx.obj['DEBUG'] = debug

@cli.command()
@click.argument('name')
@click.pass_context
def create(ctx, name):
    """建立新專案"""
    if ctx.obj['DEBUG']:
        click.echo('[DEBUG] 建立專案中...')
    click.echo(f'專案 {name} 已建立！')

@cli.command()
@click.argument('name')
@click.option('--force', is_flag=True, help='強制刪除')
def delete(name, force):
    """刪除指定專案"""
    if force or click.confirm(f'確定要刪除 {name}？'):
        click.echo(f'專案 {name} 已刪除')

這裡用到了 click.pass_context，它讓你可以在不同的子指令之間共享資料。父指令設定的 debug 旗標，子指令透過 ctx.obj 就能存取。

你也可以用巢狀 Group 做更深層的結構，像 mytool db migrate 這種多層子指令：

@cli.group()
def db():
    """資料庫相關操作"""
    pass

@db.command()
def migrate():
    """執行資料庫遷移"""
    click.echo('遷移完成')

@db.command()
def seed():
    """填入測試資料"""
    click.echo('已填入測試資料')

互動式輸入

有時候你不想讓使用者一次把所有參數都打在命令列上，而是引導他們一步步輸入。Click 的互動式功能這時就派上用場了。

click.prompt 是最基本的互動輸入：

name = click.prompt('請輸入你的名字')
age = click.prompt('年齡', type=int)
email = click.prompt('Email', default='[email protected]')

click.confirm 用來做是/否確認，超級適合危險操作前的二次確認：

if click.confirm('確定要清空所有資料嗎？', abort=True):
    click.echo('資料已清空')
# 設定 abort=True 的話，使用者按 N 會直接中斷程式

密碼輸入 用 hide_input=True，輸入時不會顯示在終端機上：

@click.option('--password', prompt=True, hide_input=True, confirmation_prompt=True)
def login(password):
    click.echo('登入成功')

這段程式碼會提示使用者輸入密碼兩次做確認，而且輸入過程完全隱藏。如果你需要記錄這些操作的日誌，可以搭配 Python logging 日誌模組教學 裡介紹的技巧。

另一個我超愛的功能是 click.edit()，它會打開系統預設的文字編輯器讓使用者輸入大段文字：

message = click.edit('在這裡輸入你的訊息...')
if message:
    click.echo(f'你輸入了：{message}')

輸出美化

命令列工具不代表輸出就要醜醜的。Click 提供了幾個好用的輸出工具，讓你的 CLI 看起來更專業。

click.echo 是 Click 版的 print，它處理了跨平台的編碼問題，比原生 print 更可靠：

click.echo('一般訊息')
click.echo('錯誤訊息', err=True)  # 輸出到 stderr

click.style 讓你的文字帶有顏色和樣式：

click.echo(click.style('成功！', fg='green', bold=True))
click.echo(click.style('警告', fg='yellow'))
click.echo(click.style('錯誤', fg='red', underline=True))

# 或用快捷方式 click.secho
click.secho('這是綠色粗體', fg='green', bold=True)

進度條 處理大量資料時特別有用：

import time

with click.progressbar(range(100), label='處理中') as bar:
    for item in bar:
        time.sleep(0.05)  # 模擬工作

Click 的進度條會自動計算剩餘時間和完成百分比，不需要你自己算。對於要處理大量檔案的情境，這個功能簡直是救星。

你也可以用 click.clear() 清除終端機畫面，或用 click.pause() 暫停等待使用者按鍵。這些小工具組合起來，就能做出使用體驗很好的 CLI 應用。

實戰：打造檔案管理 CLI 工具

好，理論講夠了，來動手做一個真正有用的東西。我們要打造一個檔案管理 CLI 工具叫 fmgr，支援以下功能：列出檔案、搜尋檔案、統計目錄大小。

import os
import click
from pathlib import Path
from datetime import datetime

@click.group()
@click.version_option(version='1.0.0')
def fmgr():
    """fmgr - 你的檔案管理好幫手"""
    pass

@fmgr.command()
@click.argument('directory', type=click.Path(exists=True, file_okay=False))
@click.option('--sort', type=click.Choice(['name', 'size', 'date']), default='name')
@click.option('--reverse', is_flag=True, help='反向排序')
@click.option('--hidden', is_flag=True, help='顯示隱藏檔案')
def ls(directory, sort, reverse, hidden):
    """列出目錄中的檔案"""
    path = Path(directory)
    entries = []

    for entry in path.iterdir():
        if not hidden and entry.name.startswith('.'):
            continue
        stat = entry.stat()
        entries.append({
            'name': entry.name,
            'size': stat.st_size,
            'date': datetime.fromtimestamp(stat.st_mtime),
            'is_dir': entry.is_dir()
        })

    sort_key = {'name': 'name', 'size': 'size', 'date': 'date'}[sort]
    entries.sort(key=lambda x: x[sort_key], reverse=reverse)

    for entry in entries:
        icon = '📁' if entry['is_dir'] else '📄'
        size = _format_size(entry['size'])
        date = entry['date'].strftime('%Y-%m-%d %H:%M')
        name_style = 'blue' if entry['is_dir'] else 'white'
        click.echo(f"  {icon} {click.style(entry['name'], fg=name_style):<30s} {size:>10s} {date}")

@fmgr.command()
@click.argument('pattern')
@click.option('--path', '-p', type=click.Path(exists=True), default='.', help='搜尋路徑')
@click.option('--ext', '-e', help='篩選副檔名（如 .py .txt）')
def search(pattern, path, ext):
    """搜尋符合條件的檔案"""
    search_path = Path(path)
    found = 0

    with click.progressbar(
        list(search_path.rglob('*')),
        label='搜尋中'
    ) as entries:
        for entry in entries:
            if not entry.is_file():
                continue
            if ext and entry.suffix != ext:
                continue
            if pattern.lower() in entry.name.lower():
                found += 1
                click.echo(f'\n  找到：{entry}')

    click.secho(f'\n共找到 {found} 個檔案', fg='green', bold=True)

@fmgr.command()
@click.argument('directory', type=click.Path(exists=True, file_okay=False))
def stats(directory):
    """統計目錄的檔案資訊"""
    path = Path(directory)
    total_size = 0
    file_count = 0
    dir_count = 0
    ext_stats = {}

    for entry in path.rglob('*'):
        if entry.is_file():
            file_count += 1
            size = entry.stat().st_size
            total_size += size
            ext = entry.suffix or '(無副檔名)'
            ext_stats[ext] = ext_stats.get(ext, 0) + 1
        elif entry.is_dir():
            dir_count += 1

    click.secho(f'\n目錄統計：{directory}', fg='cyan', bold=True)
    click.echo(f'  檔案數量：{file_count}')
    click.echo(f'  資料夾數：{dir_count}')
    click.echo(f'  總大小：  {_format_size(total_size)}')
    click.echo(f'\n  檔案類型分布：')
    for ext, count in sorted(ext_stats.items(), key=lambda x: -x[1])[:10]:
        bar = '█' * min(count, 30)
        click.echo(f'    {ext:<12s} {count:>5d} {click.style(bar, fg="cyan")}')

def _format_size(size):
    for unit in ['B', 'KB', 'MB', 'GB']:
        if size < 1024:
            return f'{size:.1f} {unit}'
        size /= 1024
    return f'{size:.1f} TB'

if __name__ == '__main__':
    fmgr()

這個工具雖然簡單，但已經展示了 Click 的多項核心功能：Group 子指令架構、多種參數類型、進度條、彩色輸出。你可以在這個基礎上繼續擴充，加入複製、移動、批次重新命名等功能。

打包與發布到 PyPI

寫好了 CLI 工具，當然要分享給其他人用嘛。Click 工具透過 setuptools 的 entry_points 就能輕鬆打包成系統命令。

首先，建立專案結構：

fmgr/
├── pyproject.toml
├── README.md
├── src/
│   └── fmgr/
│       ├── __init__.py
│       └── cli.py
└── tests/
    └── test_cli.py

在 pyproject.toml 中設定 entry point：

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "fmgr"
version = "1.0.0"
description = "一個好用的檔案管理 CLI 工具"
requires-python = ">=3.9"
dependencies = ["click>=8.0"]

[project.scripts]
fmgr = "fmgr.cli:fmgr"

最重要的是 [project.scripts] 這段，它告訴 Python 安裝這個套件時，要建立一個叫 fmgr 的系統命令，指向 fmgr.cli 模組裡的 fmgr 函式。

測試也別忘了。Click 提供了 CliRunner 來方便你寫測試：

from click.testing import CliRunner
from fmgr.cli import fmgr

def test_ls_command():
    runner = CliRunner()
    result = runner.invoke(fmgr, ['ls', '.'])
    assert result.exit_code == 0

def test_stats_command():
    runner = CliRunner()
    result = runner.invoke(fmgr, ['stats', '.'])
    assert result.exit_code == 0
    assert '檔案數量' in result.output

def test_search_not_found():
    runner = CliRunner()
    result = runner.invoke(fmgr, ['search', 'xyznonexistent'])
    assert '共找到 0 個檔案' in result.output

打包和上傳到 PyPI：

# 安裝打包工具
pip install build twine

# 打包
python -m build

# 上傳到 PyPI（需要帳號）
twine upload dist/*

上傳之後，全世界的人都能用 pip install fmgr 來安裝你的工具了。是不是很有成就感？

說真的，Click 徹底改變了我開發 CLI 工具的方式。以前一想到要寫命令列介面就煩，現在反而覺得是件樂事。如果你也有類似的痛點，強烈建議你花個下午的時間把 Click 學起來——這大概是投資報酬率最高的 Python 學習之一。整個框架的設計哲學就是讓開發者開心，而它確實做到了。