最近在使用 Nextjs 和 Python 进行 Web 项目开发，我想记录一下整个的操作和初始化的过程，便于以后自己方便查阅。

如何安排文件结构

  1. 前端 (Frontend): 这是用户在浏览器中看到和互动的部分，由 Next.js 负责。它负责显示信息、处理用户的点击和输入。
  2. 后端 (Backend): 这是在服务器上运行的部分，由 Python 负责。它负责处理数据、执行业务逻辑、与数据库交互等等。前端需要数据时，会向后端“请求”。

由于这两个部分相对独立但又需要协作，一种常见且推荐的组织方式是将它们放在同一个大的项目文件夹下，但用不同的子文件夹清楚地分开。这种方式我们有时称为“单体仓库”（monorepo），意思是所有的代码都在一个仓库里。

推荐的项目文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
my-web-app/         <-- 你的主项目文件夹
├── frontend/       <-- 存放所有 Next.js 前端代码
│   ├── app/      <-- Next.js 页面文件（用户访问的不同页面）
│   ├── components/ <-- 可重用的 UI 组件（比如按钮、导航栏）
│   ├── public/     <-- 静态文件（图片、字体等）
│   ├── styles/     <-- 样式文件（CSS等）
│   ├── utils/      <-- 前端使用的工具函数
│   ├── .env        <-- 前端环境变量
│   ├── package.json <-- Next.js 项目配置文件（依赖、脚本等）
│   ├── next.config.js <-- Next.js 配置
│   └── ... 其他 Next.js 文件
│
├── backend/        <-- 存放所有 Python 后端代码
│   ├── src/        <-- 存放后端应用的核心代码
│   │   ├── api/    <-- 处理前端请求的接口代码（例如：Flask/Django 的视图函数）
│   │   ├── models/ <-- 数据模型（例如：数据库表的定义）
│   │   ├── services/ <-- 业务逻辑代码
│   │   └── utils/  <-- 后端使用的工具函数
│   ├── config/     <-- 后端配置文件
│   ├── tests/      <-- 后端测试代码
│   ├── venv/       <-- Python 虚拟环境（可选，但推荐）
│   ├── requirements.txt <-- 后端依赖库列表
│   ├── .env        <-- 后端环境变量
│   └── app.py      <-- 后端应用的入口文件（例如：Flask 应用的启动文件）
│
├── .gitignore      <-- 告诉版本控制系统（如 Git）忽略哪些文件（比如 node_modules, venv）
├── README.md       <-- 项目说明文件（非常重要！）
└── ... 其他顶级文件

解释这个结构的重要性：

清晰分离: frontend 和 backend 两个顶层文件夹明确地分开了项目的主要部分。这意味着如果你只需要修改前端代码，你知道直接进入 frontend 文件夹；如果只需要修改后端逻辑，就进入 backend。这就像把衣服和书分别放在不同的抽屉里。

遵循框架约定: 在 frontend 文件夹内部，我们遵循 Next.js 的标准项目结构（如 pages, components 等）。在 backend 文件夹内部，虽然 Python 后端框架不同会有差异，但 api, models, services 这样的结构是很多后端应用中常见的组织方式，它帮助你按功能组织代码。

易于维护: 当项目变大时，这种结构可以帮助你快速找到你需要修改的文件。每个文件夹都有明确的职责。

易于协作: 如果你和其他人一起开发，每个人可以负责不同的部分（比如一个人负责前端，一个人负责后端），这种结构使得他们可以并行工作而不会互相干扰太多。

依赖管理: frontend 文件夹里的 package.json 管理前端的依赖库（比如 React），backend 文件夹里的 requirements.txt 管理后端的依赖库（比如 Flask 或 Django）。它们是分开管理的，互不影响。

入口点: frontend 有 Next.js 的启动方式（通常是 npm run dev 或 yarn dev），backend 有自己的启动文件（比如 app.py），它们可以独立启动和运行，只是前端需要调用后端的接口。

关于前后端如何对话

前端（Next.js）需要从后端（Python）获取数据或者发送数据给后端时，通常是通过 API (Application Programming Interface，应用程序编程接口) 来实现的。

  • 前端向后端的一个特定“地址”（URL）发送一个请求（比如一个 GET 请求来获取数据，或者一个 POST 请求来发送数据）。
  • 后端在 backend/src/api/ 文件夹中的某个文件里，会有一个对应的函数或者类来处理这个请求。
  • 后端处理完请求后，会返回一个响应（通常是 JSON 格式的数据）给前端。
  • 前端接收到响应后，就可以使用这些数据来更新页面显示。

如何初始化项目

步骤分解

  1. 创建一个主项目文件夹： 这是你所有代码的“家”。
  2. 初始化前端项目 (Next.js)： 在主文件夹内创建一个子文件夹，并在其中设置好 Next.js。
  3. 初始化后端项目 (Python)： 在主文件夹内创建另一个子文件夹，并设置好 Python 开发环境。
  4. 设置版本控制 (Git)： 帮助你追踪代码变化，方便回溯和协作。
  5. 添加重要文件： 比如说明文件 (README) 和忽略文件 (.gitignore)。

创建一个主项目文件夹

首先，在你电脑上选择一个合适的位置，创建一个新的文件夹来存放你的整个项目。你可以打开终端或命令行工具，使用以下命令：

bash

1
mkdir my-web-app
  • mkdir 是一个命令，用来“make directory”，也就是创建一个新的文件夹。
  • my-web-app 是你给这个文件夹起的名字，你可以换成你喜欢的任何名字，比如你的应用的名字。

然后进入这个文件夹：

bash

1
cd my-web-app
  • cd 是一个命令，用来“change directory”，也就是改变当前所在的文件夹。

现在，你的终端/命令行窗口应该显示你当前在 my-web-app 文件夹里了。接下来的所有操作都在这个文件夹内进行。

初始化前端项目（Next.js）

Next.js 提供了一个非常方便的命令行工具来快速创建一个新的 Next.js 项目。我们将它安装在我们刚刚创建的 my-web-app 文件夹内的 frontend 子文件夹里。

在 my-web-app 文件夹内运行以下命令：

bash

1
npx create-next-app frontend
  • npx 是一个工具，它可以让你运行 Node.js 包，而不需要先全局安装它。这很方便，因为它总会使用最新版本的 create-next-app。
  • create-next-app 是 Next.js 官方提供的初始化工具。
  • frontend 是我们告诉 create-next-app 在哪里创建项目以及给项目文件夹起什么名字。它会在 my-web-app 里面创建一个叫 frontend 的文件夹。

运行这个命令后，create-next-app 会问你一些问题来配置你的项目，比如：

  • Would you like to use TypeScript? (你想使用 TypeScript 吗？) - 对于初学者，选择 No (否) 可能更简单。
  • Would you like to use ESLint? (你想使用 ESLint 吗？) - 推荐选择 Yes (是)，它能帮助你发现代码中的问题和保持代码风格一致。
  • Would you like to use Tailwind CSS? (你想使用 Tailwind CSS 吗？) - 这是一种 CSS 框架，如果你不熟悉，可以选择 No (否)。
  • Would you like to use src/ directory? (你想使用 src/ 目录吗？) - 推荐选择 Yes (是)，这样会帮你创建 frontend/src 文件夹，符合我们之前讨论的结构。
  • Would you like to use App Router? (你想使用 App Router 吗？) - 这是 Next.js 推荐的新路由方式，推荐选择 Yes (是)。
  • Would you like to customize the default import alias? (你想自定义默认的导入别名吗？) - 对于初学者，选择 No (否) 即可。

按照你的偏好回答这些问题。create-next-app 会自动创建 frontend 文件夹，生成 Next.js 项目所需的文件，并安装所有必要的依赖库。安装完成后，你会看到 frontend 文件夹里有了 package.json, next.config.js, src/ 等文件和文件夹。

初始化后端项目（Python）

Python 后端没有一个像 create-next-app 这样通用的初始化工具（不同的框架可能有自己的工具，比如 Django 的 startproject）。我们可以手动创建文件夹结构，并设置一个虚拟环境来管理 Python 依赖。

在 my-web-app 文件夹内（确保你还在 my-web-app 里，而不是 frontend 里），创建 backend 文件夹：

bash

1
mkdir backend

进入 backend 文件夹：

bash

1
cd backend
创建并激活 Python 虚拟环境

使用虚拟环境是一个非常好的实践！它可以隔离你的项目依赖，避免不同项目之间的库版本冲突。

  • 创建虚拟环境：
  • bash
1
python -m venv venv

  • 激活虚拟环境：

    • 在 macOS 或 Linux 上：

    • bash

    • source venv/bin/activate

      1
      2
      3
      4
      5
      6
      7

      - 在 Windows 上：

      - bash

      - ```Bash
        .\venv\Scripts\activate

  • 激活后，你的终端提示符前面通常会显示 (venv)，表示你当前处于这个虚拟环境中。

创建基本的后端文件结构

现在手动创建我们讨论的后端文件夹结构：

1
2
3
mkdir src
cd src
mkdir api models services utils # 创建 src 内部的子文件夹cd .. # 回到 backend 文件夹mkdir config tests # 创建 backend 内部的子文件夹

并在 backend 文件夹里创建一些基本文件：

1
touch app.py requirements.txt .env # 在 macOS/Linux 上使用 touch，Windows 可以手动创建或使用 echo > filename

如果是 windows 上：

1
2
3
type nul > app.py
type nul > requirements.txt
type nul > .env
  • app.py 可以作为你后端应用的主入口文件。
  • requirements.txt 将用来记录你的 Python 项目依赖的库和它们的版本。
  • .env 将用来存放后端需要的环境变量（比如数据库连接信息，这些不能暴露给前端）。

现在你的 backend 文件夹里应该有 src, config, tests, app.py, requirements.txt, .env 以及 venv 文件夹。

当你安装 Python 库时（比如 pip install Flask），请确保你的虚拟环境是激活的。安装完成后，可以使用 pip freeze > requirements.txt 命令将当前虚拟环境中安装的所有库及其版本保存到 requirements.txt 文件中。

设置版本控制（Git）

Git 是一个强大的版本管理工具。

回到主项目文件夹 my-web-app。

初始化 Git 仓库：

1
git init

这会在 my-web-app 文件夹里创建一个隐藏的 .git 文件夹。

添加重要文件（.gitignore 和 README.md）

  • gitignore: 这个文件告诉 Git 哪些文件或文件夹不应该被追踪和提交。比如，node_modules (前端依赖) 和 venv (Python 虚拟环境) 文件夹通常会非常大，而且它们可以通过 package.json 和 requirements.txt 重新生成，所以不应该提交到 Git 仓库。.env文件通常包含敏感信息，也不应该提交。

在 my-web-app 文件夹里创建一个名为 .gitignore 的文件。你可以手动创建，或者使用命令：

1
2
3
touch .gitignore # macOS/Linux
# 或
type nul > .gitignore # Windows

然后用文本编辑器打开.gitignore 文件，添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Git 忽略文件列表

# Node.js 依赖文件夹 (前端)
frontend/node_modules/

# Python 虚拟环境文件夹 (后端)
backend/venv/

# 环境变量文件 (通常包含敏感信息，不应提交)
frontend/.env.local # Next.js 会生成 .env.local
frontend/.env.*.local # 其他本地环境文件
backend/.env

# 其他可能需要忽略的文件或文件夹 (可选，根据你的工具和习惯添加)
# .DS_Store # macOS 系统文件
# build/ # 前端构建输出文件夹 (Next.js 默认是 .next)
# .next/ # Next.js 构建输出文件夹
# __pycache__/ # Python 生成的缓存文件
# *.pyc # Python 编译文件
  • 这个 .gitignore 文件放在主项目文件夹 my-web-app 下，可以同时作用于 frontend 和 backend 子文件夹。
  • README.md: 一个好的 README 文件能说明你的项目是什么，如何设置，如何运行等等。这对于你自己以后回顾项目或者其他人想了解你的项目都非常有帮助。

在 my-web-app 文件夹里创建一个名为 README.md 的文件。你可以手动创建，或者使用命令：

1
2
3
touch README.md # macOS/Linux
# 或
type nul > README.md # Windows

用文本编辑器打开 README.md，写一些初步的内容，比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# 我的网页应用

这是一个使用 Next.js (前端) 和 Python (后端) 构建的网页应用。

## 项目结构

- `frontend/`: Next.js 前端代码
- `backend/`: Python 后端代码

## 设置步骤

### 前端设置

1. 进入 `frontend` 文件夹: `cd frontend`
2. 安装依赖: `npm install` 或 `yarn install` (取决于你初始化 Next.js 时选择了哪个包管理器)
3. 复制 `.env.local.example` (如果 Next.js 创建了) 或手动创建 `.env.local` 文件，并配置 `NEXT_PUBLIC_BACKEND_URL`。

### 后端设置

1. 进入 `backend` 文件夹: `cd backend`
2. 创建并激活虚拟环境:
   - macOS/Linux: `python -m venv venv` 然后 `source venv/bin/activate`
   - Windows: `python -m venv venv` 然后 `.\venv\Scripts\activate`
3. 安装依赖: `pip install -r requirements.txt` (如果 requirements.txt 是空的，你需要在安装库后生成它，比如 `pip install Flask` 后运行 `pip freeze > requirements.txt`)
4. 创建并配置 `.env` 文件。

## 如何运行

### 运行后端

1. 激活后端虚拟环境。
2. 在 `backend` 文件夹中运行后端入口文件 (例如: `python app.py`)。

### 运行前端

1. 在另一个终端窗口，进入 `frontend` 文件夹。
2. 运行开发服务器: `npm run dev` 或 `yarn dev`。
3. 打开浏览器访问 `http://localhost:3000` (Next.js 默认端口)。

## TODO

- [ ] 实现用户认证
- [ ] 连接数据库
- [ ] ...
  • 这个 README 文件可以随着项目进展不断完善。

完成初始化并进行第一次 Git 提交

现在，你的项目基本结构就搭建好了。回到 my-web-app 文件夹，将所有文件添加到 Git 并进行第一次提交：

1
2
git add . # 添加当前文件夹下所有未被 .gitignore 忽略的文件
git commit -m "Initial project setup with Next.js frontend and Python backend structure"
  • git add . 命令会将当前文件夹下（包括子文件夹）所有新的或修改过的文件添加到 Git 的“暂存区”，准备提交。.gitignore 文件中列出的文件会被忽略。
  • git commit -m "..." 命令会将暂存区的文件正式提交到 Git 仓库的历史记录中，并附上一个简短的说明消息。