環境安裝與專案建立

開始之前

任務目標

在這個任務中，我們會完成：

• 透過 uv 安裝 Python
• 使用 uv 安裝 Django
• 建立 Django 專案
• 了解 Django 專案結構
• 啟動開發伺服器
• 修改專案設定
• 建立管理者帳號
• 探索後台管理系統

安裝 Python

以前的做法

我們會從官網下載安裝檔，但這樣會有一些缺點：

• 只能有一個「系統預設」的 Python 版本
• 如果多專案使用不同 Python 管理起來很麻煩，可能需要修改設定才能順利使用
• 系統級安裝可能會影響其他應用程式
• 升級或降低版本步驟較多

後來我們會透過 pyenv 這樣的工具來達到多版本管理的目的。

但 pyenv 只負責管理 Python 版本，套件管理還是要靠 pip，虛擬環境要用 venv 或 virtualenv，工具分散在不同地方。

現代的方法：使用 uv

uv 是一個用 Rust 撰寫的現代化 Python 工具

它整合了：

• Python 版本管理 - 取代 pyenv
• 套件管理 - 取代 pip、pip-tools、poetry 等 ⋯⋯
• 虛擬環境 - 取代 venv、virtualenv
• 獨立的 cli 安裝工具 - 取代 pipx

其他優勢：

• 依賴解析 - 更快更可靠
• 極快的速度 - 比傳統工具快 10-100 倍

為什麼選擇 uv？

uv 讓我們可以用一個工具完成所有事情，不需要安裝和學習多個工具。而且它的速度非常快，能大幅提升開發效率。

安裝 uv

Windows (PowerShell)macOS / Linux

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

安裝完成後，重新開啟終端機，驗證安裝：

uv --version

想了解更多？

如果想得到更多安裝資貨可以到官網獲得更多說明

另外推薦每次安裝時到官網確認安裝指令是否有變動，免得安裝失敗

使用 uv 安裝 Python

現在我們可以用 uv 來安裝 Python：

讓我們先列出可用的 Python 版本

uv python list

接著安裝想要的版本（本教學使用 3.14）

uv python install 3.14

關於 Python 版本

本教學使用 Python 3.14，而 Django 5.x 要求的最低 Python 版本為 3.10 。

如果想了解各 Python 版本的維護週期可以參考：https://endoflife.date/python

補充說明

如果你希望在不同的資料夾預設使用指定的 Python 版本，可以使用這個指令

uv python pin 3.14

這會在當前目錄建立一個 .python-version 檔案，記錄這個資料夾要使用的 Python 版本

建立專案目錄

讓我們建立一個新的專案目錄：

mkdir django-playground
cd django-playground

使用 uv 初始化專案

uv init # (1)!

1. 如果你想要在這個時候指定 Python 版本可以這樣操作 uv init --python 3.12

uv init 會建立基本的專案結構：

django-playground/
├── .python-version  # 使用的 Python 版本
├── main.py          # 範例程式
├── pyproject.toml   # 專案設定與依賴
└── README.md        # 專案說明

我們可以試著執行範例程式

uv run main.py

uv run 指令與執行

uv run 會自動建立虛擬環境並在其中執行指令，你不需要手動啟動虛擬環境！

---

在非 uv 環境時如果想要執行一個 Python 的程式，我們會使用下方的指令

python main.py

若在 uv 環境中可能會想打成

uv run python main.py

但其實指令中的 python 是可以省略的，若你後方放的是檔案他會直接幫你使用虛擬環境中的 Python 執行

現在可以刪除 main.py 這個範例檔案：

rm main.py

安裝 Django

使用 uv 安裝 Django：

uv add django

驗證安裝，如果看到 Django 版本號，表示安裝成功！

uv run django-admin --version  # (1)!

1. django-admin 是 Django 提供的指令，跟我們安裝 uv 後有 uv 這個指令可以使用一樣，只是 Django 提供的指令叫做 django-admin

關於 Django 的版本

如果想了解各 Django 版本的維護週期可以參考：https://endoflife.date/django

建立 Django 專案

使用 Django 的 startproject 指令建立專案骨架：

uv run django-admin startproject core .

關於專案名稱

• core 是專案的主要目錄名稱
• 最後的 . 表示在當前目錄建立專案，不額外建立資料夾
• 你可以使用其他名稱，例如 config、server 等

執行完成後，專案結構如下：

django-playground/
├── .python-version
├── .venv/            # 虛擬環境（自動建立）
├── core/             # Django 配置目錄
│   ├── __init__.py
│   ├── settings.py   # 專案設定
│   ├── urls.py       # 路由設定
│   ├── asgi.py       # ASGI 設定
│   └── wsgi.py       # WSGI 設定
├── manage.py         # Django 專案進入點
├── pyproject.toml
├── README.md
└── uv.lock           # 專案依賴關係檔案（自動產生）

專案結構說明

manage.py

Django 的命令列工具，用來執行各種指令：

uv run manage.py ${command}

core/settings.py

專案的設定檔，各項設定意思可以參考官方文件

core/urls.py

專案的路由設定，定義路由與 View 的對應關係

core/wsgi.py 與 core/asgi.py

用於正式環境部署的設定檔：

• wsgi.py - 用於同步 Web 伺服器（如 Gunicorn）
• asgi.py - 用於非同步 Web 伺服器（支援 WebSocket）

啟動開發伺服器

執行以下指令啟動開發伺服器：

uv run manage.py runserver

你會看到這樣的輸出：

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
November 07, 2025 - 17:34:14
Django version 5.2.8, using settings 'core.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/5.2/howto/deployment/

這時候就可以開啟瀏覽器，前往 http://127.0.0.1:8000/，你應該會看到 Django 的歡迎頁面！

探索管理後台

Django 內建了一個功能強大的管理後台。前往 http://127.0.0.1:8000/admin/，你會看到登入頁面。

在一行程式都還沒寫的情況下能看到登入畫面是因為 Django 內建了使用者認證、管理介面等功能。但這些功能需要資料庫支援，先讓我們把資料庫建立起來。

現在先讓我們按下 Ctrl+C 停止伺服器的執行，接著執行 migrate 指令來建立必要的資料表：

uv run manage.py migrate  # (1)!

1. 我們後面會更詳細的解釋這個指令，先理解他的目的是為了建立資料表就好

你會看到這樣的輸出代表表都建立完成了

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying admin.0003_logentry_add_action_flag_choices... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying auth.0009_alter_user_last_name_max_length... OK
  Applying auth.0010_alter_group_name_max_length... OK
  Applying auth.0011_update_proxy_permissions... OK
  Applying auth.0012_alter_user_first_name_max_length... OK
  Applying sessions.0001_initial... OK

資料庫在哪裡？

Django 預設使用 SQLite 資料庫，會在專案根目錄建立一個 db.sqlite3 檔案。

現在還沒有管理員帳號，讓我們建立一個：

uv run manage.py createsuperuser

接著依照提示輸入資訊：

Username (leave blank to use 'user'): admin
Email address: [email protected]
Password:
Password (again):
This password is too short. It must contain at least 8 characters.
This password is too common.
This password is entirely numeric.
Bypass password validation and create user anyway? [y/N]: y
Superuser created successfully.

提醒事項

1. Password: 與 Password (again): 這兩格，在輸入時不會有字元跳出是正常的他是為了保護你的密碼，你只要在輸入完成後按下 Enter 即可
2. 上方框選起來的內容只有在你的密碼太過簡單食材會跳出，你輸入 Y 後即可跳過密碼複雜度驗證

再次啟動伺服器：

uv run manage.py runserver

前往 http://127.0.0.1:8000/admin/，使用剛才建立的帳號登入

現在你可以看到管理後台了！你可以在這裡管理使用者、群組等資料。

調整專案設定

開啟 core/settings.py，調整語言和時區設定。

找到這兩行：

LANGUAGE_CODE = 'en-us'

TIME_ZONE = 'UTC'

改為：

LANGUAGE_CODE = 'zh-hant'

TIME_ZONE = 'Asia/Taipei'

這時再回到網頁 http://127.0.0.1:8000/admin/ 中，就會發現 Django 的介面就會顯示繁體中文，時間也會使用台灣時區。

任務結束

任務完成

恭喜你完成任務一！現在你已經：

• 透過 uv 安裝 Python
• 使用 uv 安裝 Django
• 建立 Django 專案
• 了解 Django 專案結構
• 啟動開發伺服器
• 修改專案設定
• 建立管理者帳號
• 探索後台管理系統

常見問題

為什麼要用 uv 而不是 pip 或其他工具？

uv 的優勢：

• 整合了 Python 版本管理、套件管理、虛擬環境，省去眾多的工具
• 速度相比其他工具快了約 10-100 倍
• 更好的依賴解析，避免套件衝突
• 自動管理虛擬環境，不需要手動啟動

需要手動啟動虛擬環境嗎？

不需要！使用 uv run 會自動在虛擬環境中執行指令。如果你想手動啟動虛擬環境：

WindowsmacOS / Linux

.venv\Scripts\activate

source .venv/bin/activate

啟動後就不需要加 uv run 前綴了。

db.sqlite3 是什麼？

這是 Django 預設使用的 SQLite 資料庫檔案。SQLite 是一個輕量級資料庫，適合開發和小型專案。正式環境通常會使用 PostgreSQL 或 MySQL。

開發伺服器可以用於正式環境嗎？

不行！runserver 只適合開發使用。正式環境應該使用生產級別的伺服器，例如：

• Gunicorn (WSGI)
• Uvicorn (ASGI)
• uWSGI
• Daphne