前言

在 Python 開(kāi)發(fā)中，“能跑就行”和“工程化”之間往往只隔著一個(gè)合理的目錄結(jié)構(gòu)。很多開(kāi)發(fā)者在項(xiàng)目初期隨意擺放文件，導(dǎo)致后期出現(xiàn)循環(huán)導(dǎo)入、打包困難、路徑混亂等問(wèn)題。本文將從零開(kāi)始，帶你打造一個(gè)專(zhuān)業(yè)級(jí)的 Python 工程，涵蓋目錄結(jié)構(gòu)、模塊導(dǎo)入、開(kāi)發(fā)模式安裝，以及 VSCode 的完美配置。

1. 為什么推薦src/目錄結(jié)構(gòu)？

很多初學(xué)者習(xí)慣將代碼直接放在項(xiàng)目根目錄下（扁平結(jié)構(gòu)），但對(duì)于中大型項(xiàng)目或需要打包發(fā)布的庫(kù)，src/ 結(jié)構(gòu)是行業(yè)標(biāo)準(zhǔn)（Django、Pandas、Flit 均采用此結(jié)構(gòu)）。它能有效隔離源代碼與項(xiàng)目配置，避免許多隱式錯(cuò)誤。

1.1 標(biāo)準(zhǔn)結(jié)構(gòu)對(duì)比

? 不推薦的扁平結(jié)構(gòu)（易出錯(cuò)）：

my_project/
├── my_package/      # 包
│   ├── __init__.py
│   └── module.py
├── main.py          # 入口腳本
└── setup.py

風(fēng)險(xiǎn)：運(yùn)行 python main.py 時(shí)，Python 會(huì)將當(dāng)前目錄 my_project/ 加入 sys.path。如果 my_package 和 main.py 互相導(dǎo)入，極易引發(fā)循環(huán)導(dǎo)入或命名空間污染。此外，tests/ 目錄混在根目錄下，打包時(shí)可能被意外包含。

? 推薦的 src 結(jié)構(gòu)：

my_project/
├── src/             # 源代碼根目錄
│   └── my_package/  # 實(shí)際的包
│       ├── __init__.py
│       ├── module_a.py
│       └── sub_package/
│           ├── __init__.py
│           └── module_b.py
├── tests/           # 測(cè)試目錄
├── .gitignore
├── pyproject.toml   # 現(xiàn)代打包配置（替代 setup.py）
├── README.md
└── LICENSE

1.2src/的核心優(yōu)勢(shì)

1. 避免意外導(dǎo)入：代碼在 src/ 下，運(yùn)行時(shí)必須安裝或指定路徑才能導(dǎo)入，防止了“因?yàn)閯偤迷谕?jí)目錄就能 import”導(dǎo)致的隱式依賴(lài)。
2. 解決循環(huán)導(dǎo)入：物理隔離了源代碼和腳本，強(qiáng)制使用包的方式引用，減少循環(huán)依賴(lài)風(fēng)險(xiǎn)。
3. 打包更干凈：打包時(shí)只需指定 src/ 為源目錄，不會(huì)把 tests/、docs/ 等無(wú)關(guān)文件打進(jìn)去。
4. 明確邊界：清晰區(qū)分“可安裝的代碼”和“項(xiàng)目配置/測(cè)試”。

1.3src/帶來(lái)的“麻煩”及解決方案

src/ 結(jié)構(gòu)確實(shí)增加了一點(diǎn)復(fù)雜度：直接運(yùn)行 python src/my_package/main.py 會(huì)報(bào) ModuleNotFoundError。

解決方案：

1. 開(kāi)發(fā)模式（推薦）：使用 可編輯安裝。

   # 在項(xiàng)目根目錄執(zhí)行
   pip install -e .

   這樣 Python 環(huán)境會(huì)鏈接到 src/，之后你可以像普通包一樣 import my_package。
2. 運(yùn)行模式：使用 -m 參數(shù)。

   # 切換到項(xiàng)目根目錄，使用模塊方式運(yùn)行
   python -m my_package.main

2. 模塊引用指南：相對(duì)導(dǎo)入 vs 絕對(duì)導(dǎo)入

在 src/ 結(jié)構(gòu)下，理解導(dǎo)入語(yǔ)法至關(guān)重要。

2.1 核心符號(hào)含義

在 from .文件名 import ... 中：

• . (單點(diǎn))：代表當(dāng)前包（當(dāng)前目錄）。
• .. (雙點(diǎn))：代表父級(jí)包（上一級(jí)目錄）。
• 限制：只能在包內(nèi)的模塊中使用（即目錄必須有 __init__.py，Python 3.3+ 支持隱式命名空間包，但建議顯式創(chuàng)建 __init__.py 以明確包邊界）。
• 禁忌：不能在頂層腳本（直接運(yùn)行的 .py 文件）中使用，否則報(bào)錯(cuò) ImportError: attempted relative import with no known parent package。

2.2 實(shí)戰(zhàn)場(chǎng)景演示

假設(shè)結(jié)構(gòu)如下：

src/
└── my_package/
    ├── __init__.py
    ├── module_a.py
    └── sub_package/
        ├── __init__.py
        └── module_b.py

場(chǎng)景 A：同級(jí)模塊引用

需求：在 module_a.py 中導(dǎo)入 sub_package/module_b.py。

# src/my_package/module_a.py

# 錯(cuò)誤 ?: from module_b import x (會(huì)去系統(tǒng)路徑找，找不到)
# 正確 ?: 從當(dāng)前包(my_package)進(jìn)入 sub_package
from .sub_package.module_b import some_function

場(chǎng)景 B：下級(jí)模塊引用（父引用子）

同上，也是相對(duì)導(dǎo)入的一種。

場(chǎng)景 C：上級(jí)/跨級(jí)引用（子引用父）

需求：在 module_b.py 中導(dǎo)入 module_a.py。

# src/my_package/sub_package/module_b.py

# .. 表示返回上一級(jí)包 (my_package)
from ..module_a import some_function

場(chǎng)景 D：頂層腳本引用包（絕對(duì)導(dǎo)入）

需求：在項(xiàng)目根目錄的 main.py 或外部腳本中引用。

# main.py (位于項(xiàng)目根目錄，非 src 內(nèi))

# 必須使用絕對(duì)導(dǎo)入
from my_package.module_a import some_function
from my_package.sub_package.module_b import another_function

# 嚴(yán)禁使用: from .my_package import ... (會(huì)報(bào)錯(cuò))

2.3 相對(duì)導(dǎo)入 vs 絕對(duì)導(dǎo)入 對(duì)比表

最佳實(shí)踐建議：

• 包內(nèi)部（.py 之間）：優(yōu)先用相對(duì)導(dǎo)入（from . import）。
• 包外部（腳本引用包）：必須用絕對(duì)導(dǎo)入（from my_package import）。

3. 開(kāi)發(fā)神器：pip install -e(可編輯模式)

當(dāng)你采用 src/ 結(jié)構(gòu)或開(kāi)發(fā)一個(gè)庫(kù)時(shí)，pip install -e . 是必備技能。

3.1 它是做什么的？

• -e 是 --editable 的縮寫(xiě)。
• 普通安裝 (pip install .)：將代碼復(fù)制到 Python 的 site-packages 目錄。修改源碼后需重新安裝才生效。
• 可編輯安裝 (pip install -e .)：在 site-packages 中創(chuàng)建一個(gè)鏈接文件（.egg-link 或 .pth），指向你的本地源碼路徑。

3.2 核心價(jià)值

修改代碼，立即生效，無(wú)需重裝！

3.3 適用場(chǎng)景

1. 開(kāi)發(fā)庫(kù)/框架：你在開(kāi)發(fā) mylib，同時(shí)有個(gè) test_app 在引用它。在 mylib 目錄下 pip install -e .，test_app 就能直接用最新版 mylib。
2. 本地項(xiàng)目聯(lián)調(diào)：多個(gè)微服務(wù)或模塊在本地，互相依賴(lài)，用 -e 安裝彼此。
3. 調(diào)試第三方庫(kù)：克隆開(kāi)源庫(kù)代碼，修改后用 -e 安裝到環(huán)境中進(jìn)行調(diào)試。

3.4 注意事項(xiàng)

• 必須有打包配置：項(xiàng)目需包含 setup.py 或3.6+PEP 518版本之后的 pyproject.toml（推薦）。
• 路徑敏感：如果移動(dòng)了項(xiàng)目文件夾，鏈接會(huì)失效，需重新安裝。
• 建議用虛擬環(huán)境：避免污染全局環(huán)境，方便隨時(shí)刪除重試。
• 卸載：使用 pip uninstall 包名 即可移除鏈接。

4. 標(biāo)準(zhǔn)工程及 VSCode 配置全攻略

假設(shè)我們的項(xiàng)目結(jié)構(gòu)如下：

my_awesome_project/
├── .vscode/                  # VSCode 配置目錄（建議加入 .gitignore）
│   ├── settings.json
│   └── launch.json
├── src/
│   └── my_awesome_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils/
│       │   ├── __init__.py
│       │   └── helpers.py
│       └── main.py           # 可選入口
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── .gitignore
├── pyproject.toml            # 現(xiàn)代打包配置
└── README.md

代碼內(nèi)容：

1. src/my_awesome_package/utils/helpers.py

   def helper_func():
       return "I am a helper"

2. src/my_awesome_package/core.py (引用子模塊)

   # 從同級(jí)的 utils 子包導(dǎo)入 helpers
   from .utils.helpers import helper_func
   
   def main_logic():
       print(f"Core logic calling: {helper_func()}")
   

3. src/my_awesome_package/main.py (包內(nèi)入口，引用同級(jí))

   from .core import main_logic
   
   if __name__ == "__main__":
       # 注意：這里不能用相對(duì)導(dǎo)入，因?yàn)檫@是直接運(yùn)行的腳本
       # 但因?yàn)榘惭b了包，可以用絕對(duì)導(dǎo)入，或者用 -m 運(yùn)行
       main_logic()
   

4. pyproject.toml (現(xiàn)代 Python 打包配置)

   [build-system]
   requires = ["setuptools>=61.0", "wheel"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "my_awesome_package"
   version = "0.1.0"
   description = "A fantastic package"
   readme = "README.md"
   requires-python = ">=3.8"
   license = {text = "MIT"}
   
   [tool.setuptools.packages.find]
   where = ["src"]
   

如何運(yùn)行與開(kāi)發(fā)：

# 1. 創(chuàng)建虛擬環(huán)境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. 可編輯安裝 (關(guān)鍵步驟！)
pip install -e .

# 3. 安裝開(kāi)發(fā)依賴(lài)（如 pytest）
pip install pytest black

# 4. 運(yùn)行測(cè)試或腳本
python -m my_awesome_package.main
pytest tests/

4.1 選擇解釋器 (Select Interpreter)

這是第一步，也是最重要的一步。

1. 按 Ctrl+Shift+P (Mac: Cmd+Shift+P)。
2. 輸入 Python: Select Interpreter。
3. 選擇你項(xiàng)目虛擬環(huán)境（如 ./venv/bin/python）中的 Python 解釋器。
   • 關(guān)鍵：確保你已經(jīng)在終端運(yùn)行了 pip install -e .，這樣 Python 環(huán)境才能識(shí)別 my_awesome_package。

4.2 配置智能提示與路徑識(shí)別 (settings.json)

如果不配置，VSCode 的 Pylance 可能會(huì)在 from my_awesome_package import ... 下畫(huà)紅線(xiàn)，提示 Import "my_awesome_package" could not be resolved。

解決方法：在項(xiàng)目根目錄創(chuàng)建 .vscode/settings.json，添加 python.analysis.extraPaths。

{
    "python.analysis.extraPaths": ["./src"],
    "python.testing.pytestArgs": ["tests"],
    "python.testing.unittestEnabled": false,
    "python.testing.pytestEnabled": true,
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.black-formatter",
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    }
}

核心配置解釋：

• "python.analysis.extraPaths": ["./src"]：
  • 告訴 Pylance：“請(qǐng)把 ./src 目錄當(dāng)作源碼根目錄去掃描”。這樣 from my_awesome_package.core import ... 就不會(huì)報(bào)錯(cuò)了。
• 測(cè)試配置：?jiǎn)⒂?pytest 并指定測(cè)試目錄。
• 格式化配置：保存時(shí)自動(dòng)用 Black 格式化，并自動(dòng)整理 import（需安裝 isort 插件或使用 Black 結(jié)合）。

4.3 配置調(diào)試與運(yùn)行 (launch.json)

在 src/ 結(jié)構(gòu)下，直接按 F5 運(yùn)行當(dāng)前打開(kāi)的文件（如 src/my_awesome_package/main.py）通常會(huì)失敗，因?yàn)?Python 會(huì)把當(dāng)前文件所在目錄加入路徑，導(dǎo)致相對(duì)導(dǎo)入混亂。

正確做法：使用 module 模式，模擬 python -m 命令。

在 .vscode/ 下創(chuàng)建 launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 運(yùn)行主程序 (Module模式)",
            "type": "python",
            "request": "launch",
            "module": "my_awesome_package.main",
            "console": "integratedTerminal",
            "justMyCode": true,
            "cwd": "${workspaceFolder}"
        },
        {
            "name": "Python: 調(diào)試當(dāng)前文件 (謹(jǐn)慎使用)",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "PYTHONPATH": "${workspaceFolder}/src"
            },
            "justMyCode": true
        },
        {
            "name": "Python: 調(diào)試當(dāng)前測(cè)試",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "purpose": ["debug-test"],
            "console": "integratedTerminal"
        },
        {
            "name": "Python: 運(yùn)行所有測(cè)試 (Pytest)",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": ["-v", "tests/"],
            "console": "integratedTerminal"
        }
    ]
}

配置詳解：

1. "module": "my_awesome_package.main"：
   • 這等同于在終端執(zhí)行 python -m my_awesome_package.main。VSCode 會(huì)自動(dòng)處理 sys.path，確保能正確找到包。
   • 注意：這里不需要寫(xiě) src. 前綴，因?yàn)榘呀?jīng)安裝到了環(huán)境。
2. "cwd": "${workspaceFolder}"：將運(yùn)行時(shí)的工作目錄鎖定在項(xiàng)目根目錄。
3. 調(diào)試當(dāng)前文件：提供一個(gè)備用方案，但需手動(dòng)設(shè)置 PYTHONPATH 作為保險(xiǎn)。不過(guò)，包內(nèi)文件仍可能因相對(duì)導(dǎo)入失敗，建議優(yōu)先使用 Module 模式。
4. 測(cè)試調(diào)試：直接利用 VSCode 的測(cè)試調(diào)試功能。

4.4 集成測(cè)試流程

配置好 settings.json 中的 pytest 參數(shù)后：

1. 打開(kāi)側(cè)邊欄的 “測(cè)試” 圖標(biāo) (燒杯形狀)。
2. VSCode 會(huì)自動(dòng)發(fā)現(xiàn) tests/ 下所有 test_*.py 文件。
3. 點(diǎn)擊文件名旁的 “運(yùn)行測(cè)試” 或 “調(diào)試測(cè)試” 按鈕即可。

如果測(cè)試代碼中需要導(dǎo)入源碼：

# tests/test_core.py
from my_awesome_package.core import main_logic

def test_main_logic():
    assert main_logic() is not None   # 假設(shè) main_logic 返回 None，此處僅為示例

5. 完整開(kāi)發(fā)工作流 (Cheat Sheet)

5.1 初始化項(xiàng)目

mkdir my_awesome_project && cd my_awesome_project
mkdir -p src/my_awesome_package tests .vscode
touch src/my_awesome_package/__init__.py
touch tests/__init__.py
# 創(chuàng)建其他文件...

5.2 設(shè)置虛擬環(huán)境與依賴(lài)

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install --upgrade pip
pip install -e .          # 可編輯安裝你的包
pip install pytest black isort  # 安裝開(kāi)發(fā)工具
pip freeze > requirements-dev.txt  # 可選，保存開(kāi)發(fā)依賴(lài)

5.3 VSCode 配置

• 創(chuàng)建 .vscode/settings.json (配置 extraPaths、格式化等)。
• 創(chuàng)建 .vscode/launch.json (配置 module 運(yùn)行模式)。
• 安裝推薦插件：Python (by Microsoft), Pylance, Black Formatter.

5.4 編寫(xiě)代碼與調(diào)試

• 寫(xiě)代碼：在 src/my_awesome_package/ 下編寫(xiě)，利用 Pylance 的自動(dòng)補(bǔ)全。
• 運(yùn)行：按 F5 選擇 “Python: 運(yùn)行主程序 (Module模式)”。
• 調(diào)試：在代碼行號(hào)左側(cè)打紅點(diǎn)，按 F5 啟動(dòng)調(diào)試。
• 測(cè)試：在 tests/ 下寫(xiě)測(cè)試用例，利用側(cè)邊欄 Test 圖標(biāo)運(yùn)行。

6. 常見(jiàn) VSCode 問(wèn)題排查

7. 總結(jié)

1. 目錄結(jié)構(gòu)：中大型項(xiàng)目首選 src/ 結(jié)構(gòu)，小型腳本可用扁平結(jié)構(gòu)，但建議盡早養(yǎng)成好習(xí)慣。
2. 導(dǎo)入規(guī)則：包內(nèi)部用 相對(duì)導(dǎo)入 (. 和 ..)，頂層腳本用 絕對(duì)導(dǎo)入。
3. 開(kāi)發(fā)流程：養(yǎng)成 pip install -e . 的習(xí)慣，配合虛擬環(huán)境，開(kāi)發(fā)體驗(yàn)極佳。
4. 打包意識(shí)：即使不發(fā)布到 PyPI，也要寫(xiě)好 pyproject.toml，這是現(xiàn)代 Python 工程化的基石。
5. VSCode 配置：
   • settings.json -> extraPaths 解決 智能提示。
   • launch.json -> module 模式解決 運(yùn)行/調(diào)試。
6. 測(cè)試集成：利用 VSCode 的測(cè)試面板，一鍵運(yùn)行 pytest，事半功倍。

配置好這些后，你的 Python 工程將擁有專(zhuān)業(yè)級(jí)的開(kāi)發(fā)體驗(yàn)：代碼提示精準(zhǔn)、調(diào)試順暢、測(cè)試自動(dòng)化?，F(xiàn)在就動(dòng)手重構(gòu)你的項(xiàng)目吧！ ??

到此這篇關(guān)于Python工程化實(shí)戰(zhàn)之從目錄結(jié)構(gòu)到VSCode完美配置指南的文章就介紹到這了,更多相關(guān)Python目錄結(jié)構(gòu)到VSCode配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論