嵌入式 C 多文件項目結構：.c/.h 相互包含、模塊劃分與編譯器配置最佳實踐

嵌入式 C 多文件項目結構最佳實踐

背景痛點

接手他人代碼常見問題：所有邏輯塞在 main.c、頭文件濫用、變量重複定義、難以定位功能、維護成本極高。規範的多文件結構是團隊協作與長期維護的基石。

模塊劃分原則

按功能內聚劃分模塊，每模塊一對 .c/.h：

• main.c/.h：系統初始化、主循環、全局狀態標志位。
• uart.c/.h：串口/I2C 通信驅動、myprintf 等工具函數。
• key.c/.h：按鍵/撥碼開關掃描、去抖動。
• flash.c/.h：Flash 讀寫封裝。
• battery.c/.h：電池管理（ADC 採樣、電量估算）。
• power.c/.h：電源控制邏輯（開關機時序、保護）。

目錄結構示例

PROJECT/
├── PROJ/           # 工程文件
├── APP/
│   ├── main.c
│   ├── main.h
│   └── aplication.c
├── BASEDRIVE/
│   ├── uart.c
│   └── uart.h
├── EXTIDRIVE/
│   ├── flash.c
│   └── flash.h
└── DOC/
    └── Readme.md

編譯器包含路徑配置（避免絕對路徑）

• IAR：Project → Options → C/C++ Compiler → Preprocessor → Additional include directories → 添加 $PROJ_DIR$/../BASEDRIVE 等相對路徑。
• Keil MDK：Options for Target → C/C++ → Include Paths → 添加相對路徑。

之後在代碼中直接 #include "uart.h" 即可，無需寫路徑。

核心規範：變量/函數聲明與定義分離

原則

1. 定義在 .c：靜態/全局變量、函數體定義在 .c 內部。
2. 聲明在 .h：需跨文件訪問的變量/函數，在 .h 用 extern 聲明。
3. 宏定義在 .h：常量、配置宏直接在 .h 定義。
4. 內部函數/變量加 static：僅本文件使用的函數/變量，定義時加 static，不在 .h 暴露。

正例：uart 模塊

// uart.c
static uint8_t uart_rx_buf[64];      // 內部緩衝區，不對外
static uint8_t uart_rx_len = 0;

uint8_t uart_tx_busy_flag = 0;       // 需外部查詢，定義在 .c
void uart_init(void) { ... }         // 定義
void myprintf(const char *str) { ... }

// uart.h
#ifndef __UART_H__
#define __UART_H__
#include 

extern uint8_t uart_tx_busy_flag;    // 聲明
void uart_init(void);                // 聲明
void myprintf(const char *str);      // 聲明

#define UART_BAUDRATE 115200         // 宏定義
#endif

反例：直接在 .h 定義變量

// 錯誤！多個 .c 包含此 .h 會導致重複定義鏈接錯誤
// uart.h
uint8_t uart_tx_busy_flag = 0;  // 定義！

即使加 #ifndef 防衛，也只能防止同一編譯單元重複包含，**無法防止不同 .c 編譯後鏈接時符號重複**。

主文件匯總包含

// main.c
#include "main.h"
#include "uart.h"
#include "key.h"
#include "flash.h"
#include "battery.h"
#include "power.h"

// 全局狀態定義在 main.c，聲明在 main.h 供其他模塊訪問
system_state_t g_sys_state = STATE_IDLE;

總結清單

結語

嵌入式項目規模雖小，但「高內聚、低耦合、清晰所有權」的工程化原則同樣適用。建立規範的多文件結構，不僅為團隊協作鋪路，更是對自己未來維護工作的最大善意。