前言

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

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

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

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

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

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

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

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

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

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

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

1.3src/帶來的“麻煩”及解決方案

src/ 結(jié)構(gòu)確實增加了一點復(fù)雜度：直接運行 python src/my_package/main.py 會報 ModuleNotFoundError。

解決方案：

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

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

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

   # 切換到項目根目錄，使用模塊方式運行
   python -m my_package.main

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

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

2.1 核心符號含義

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

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

2.2 實戰(zhàn)場景演示

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

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

場景 A：同級模塊引用

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

# src/my_package/module_a.py

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

場景 B：下級模塊引用（父引用子）

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

場景 C：上級/跨級引用（子引用父）

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

# src/my_package/sub_package/module_b.py

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

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

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

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

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

# 嚴禁使用: from .my_package import ... (會報錯)

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

最佳實踐建議：

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

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

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

3.1 它是做什么的？

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

3.2 核心價值

修改代碼，立即生效，無需重裝！

3.3 適用場景

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

3.4 注意事項

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

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

假設(shè)我們的項目結(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 (引用子模塊)

   # 從同級的 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)入口，引用同級)

   from .core import main_logic
   
   if __name__ == "__main__":
       # 注意：這里不能用相對導(dǎo)入，因為這是直接運行的腳本
       # 但因為安裝了包，可以用絕對導(dǎo)入，或者用 -m 運行
       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"]
   

如何運行與開發(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. 安裝開發(fā)依賴（如 pytest）
pip install pytest black

# 4. 運行測試或腳本
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. 選擇你項目虛擬環(huán)境（如 ./venv/bin/python）中的 Python 解釋器。
   • 關(guān)鍵：確保你已經(jīng)在終端運行了 pip install -e .，這樣 Python 環(huán)境才能識別 my_awesome_package。

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

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

解決方法：在項目根目錄創(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：“請把 ./src 目錄當(dāng)作源碼根目錄去掃描”。這樣 from my_awesome_package.core import ... 就不會報錯了。
• 測試配置：啟用 pytest 并指定測試目錄。
• 格式化配置：保存時自動用 Black 格式化，并自動整理 import（需安裝 isort 插件或使用 Black 結(jié)合）。

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

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

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

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

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 運行主程序 (Module模式)",
            "type": "python",
            "request": "launch",
            "module": "my_awesome_package.main",
            "console": "integratedTerminal",
            "justMyCode": true,
            "cwd": "${workspaceFolder}"
        },
        {
            "name": "Python: 調(diào)試當(dāng)前文件 (謹慎使用)",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "PYTHONPATH": "${workspaceFolder}/src"
            },
            "justMyCode": true
        },
        {
            "name": "Python: 調(diào)試當(dāng)前測試",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "purpose": ["debug-test"],
            "console": "integratedTerminal"
        },
        {
            "name": "Python: 運行所有測試 (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 會自動處理 sys.path，確保能正確找到包。
   • 注意：這里不需要寫 src. 前綴，因為包已經(jīng)安裝到了環(huán)境。
2. "cwd": "${workspaceFolder}"：將運行時的工作目錄鎖定在項目根目錄。
3. 調(diào)試當(dāng)前文件：提供一個備用方案，但需手動設(shè)置 PYTHONPATH 作為保險。不過，包內(nèi)文件仍可能因相對導(dǎo)入失敗，建議優(yōu)先使用 Module 模式。
4. 測試調(diào)試：直接利用 VSCode 的測試調(diào)試功能。

4.4 集成測試流程

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

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

如果測試代碼中需要導(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. 完整開發(fā)工作流 (Cheat Sheet)

5.1 初始化項目

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)境與依賴

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

5.3 VSCode 配置

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

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

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

6. 常見 VSCode 問題排查

7. 總結(jié)

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

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

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

最新評論