1.配置环境、创建项目与导航栏

配置环境、创建项目与导航栏

一、目标

完成项目从 0 到 1 的搭建：

• 配置 Python、Node.js、Git、IDE 等开发环境；
• 创建 Django 后端项目与 Vue 3 前端项目；
• 配置 DRF、JWT、CORS、静态文件和媒体文件；
• 使用 Tailwind CSS + DaisyUI 搭建基础导航栏；
• 理解开发环境与生产部署环境的区别；
• 完成前端打包到 Django 后端的基础整合。

本节是整个 AgentTalk 项目的地基，后续登录、角色、聊天、语音模块都建立在这里的前后端工程结构之上。

---

二、开发环境配置

2.1 Python 与虚拟环境

后端使用 Django，因此需要安装 Python，并建议使用虚拟环境隔离依赖。

python -m venv .venv
.venv\Scripts\activate

Linux / macOS：

python -m venv .venv
source .venv/bin/activate

虚拟环境的作用：

• 每个项目拥有独立依赖；
• 避免全局 Python 包版本冲突；
• 方便通过 requirements.txt 复现环境。

2.2 Node.js 与 npm

前端使用 Vue 3 + Vite，需要 Node.js 提供构建工具运行环境。

安装地址：https://nodejs.org/

安装时建议勾选 Add to PATH。

更新 npm：

npm install -g npm@latest

Node.js 在本项目中的作用：

1. 运行 Vite 开发服务器；
2. 管理 Vue、Pinia、DaisyUI 等前端依赖；
3. 执行 npm run build，将 Vue 源码打包成浏览器可运行的静态文件。

2.3 Git 与 SSH

安装 Git：https://gitforwindows.org/

生成 SSH Key：

ssh-keygen

常用 Git 命令：

git status
git add .
git commit -m "提交说明"
git push
git pull
git clone <repo-url>

重点理解

• git status：查看工作区与暂存区状态；
• git add：将修改加入暂存区；
• git commit：生成本地提交记录；
• git push：推送到远程仓库；
• .gitignore：忽略不应该提交的文件，如虚拟环境、数据库、环境变量、打包产物。

2.4 PyCharm / IDE 配置

如果使用 PyCharm：

1. 安装中文插件：Settings -> Plugins -> Marketplace；
2. 开启 Django 支持：Settings -> Languages & Frameworks -> Django；
3. 配置 Django project root、settings、manage.py；
4. 将 backend 目录标记为 Sources Root，避免无法识别 web 模块。

---

三、创建 Django 后端

3.1 创建项目与应用

django-admin startproject backend
cd backend
django-admin startapp web
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

目录含义：

backend/
├── backend/          # Django 项目配置包
│   ├── settings.py   # 全局配置
│   ├── urls.py       # 根路由
│   ├── wsgi.py       # WSGI 部署入口
│   └── asgi.py       # ASGI 部署入口
├── web/              # 业务应用
│   ├── models.py     # 默认模型文件，后续可拆成 models/ 目录
│   ├── views.py      # 默认视图文件，后续可拆成 views/ 目录
│   └── urls.py       # web 应用子路由，需自行创建
└── manage.py         # Django 管理脚本

3.2 安装后端依赖

pip install django
pip install djangorestframework
pip install djangorestframework-simplejwt
pip install django-cors-headers
pip install pillow

依赖说明：

包	作用
django	后端 Web 框架
djangorestframework	编写 REST API
djangorestframework-simplejwt	JWT 登录认证
django-cors-headers	处理跨域
pillow	处理图片上传字段

---

四、配置 Django settings.py

4.1 注册应用

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    'rest_framework',
    'corsheaders',
    'web',
]

4.2 跨域中间件

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

CorsMiddleware 应尽量放在靠前位置。

4.3 时区

TIME_ZONE = 'Asia/Shanghai'
USE_TZ = True

4.4 静态文件与媒体文件

STATIC_URL = 'static/'

STATICFILES_DIRS = [
    BASE_DIR / 'static',
]

MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

static 与 media 区别

类型	含义	示例
static	开发者提供的静态资源	JS、CSS、前端打包文件
media	用户上传的动态文件	头像、角色背景图

4.5 JWT 配置

from datetime import timedelta

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(hours=2),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'AUTH_HEADER_TYPES': ('Bearer',),
}

4.6 CORS 配置

CORS_ALLOW_CREDENTIALS = True

CORS_ALLOWED_ORIGINS = [
    'http://localhost:5173',
    'http://127.0.0.1:5173',
]

CORS_ALLOW_CREDENTIALS = True 用于允许跨域请求携带 Cookie。

---

五、配置后端路由与前端入口

5.1 项目根路由

backend/backend/urls.py：

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('web.urls')),
]

if settings.DEBUG:
    urlpatterns += static('/media/', document_root=settings.MEDIA_ROOT)

5.2 web 子路由

backend/web/urls.py：

from django.urls import path, re_path
from web.views.index import index

urlpatterns = [
    path('', index),
    re_path(r'^(?!media/|static/|assets/).*$', index),
]

5.3 前端 History 模式刷新问题

Vue Router 使用 createWebHistory() 时，浏览器访问 /friend、/create 等路径会先请求后端。

如果后端没有对应路由，会出现 404。因此需要：

re_path(r'^(?!media/|static/|assets/).*$', index)

含义：

• 排除媒体和静态资源路径；
• 其他路径都返回同一个 index.html；
• 真正的页面匹配交给 Vue Router 完成。

---

六、创建 Vue 3 前端

6.1 创建项目

npm create vue@latest
cd frontend
npm install

推荐选择：

• Vue Router；
• Pinia；
• ESLint / Prettier 可按需要选择。

6.2 安装 Tailwind CSS 与 DaisyUI

npm install -D tailwindcss @tailwindcss/vite
npm install -D daisyui

在 frontend/src/assets/main.css 中：

@import "tailwindcss";
@plugin "daisyui";

6.3 配置 Vite 打包输出

frontend/vite.config.js：

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  build: {
    outDir: path.resolve(__dirname, '../backend/static/frontend'),
    emptyOutDir: true,
  },
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

这样执行：

npm run build

前端产物会输出到 Django 的 backend/static/frontend。

---

七、前端基础结构

frontend/src/
├── App.vue                 # 根组件
├── main.js                 # 入口文件
├── router/index.js         # 路由配置
├── stores/                 # Pinia 状态
├── components/             # 公共组件
│   └── navbar/             # 导航栏组件
└── views/                  # 页面组件
    ├── homepage/
    ├── friend/
    ├── create/
    ├── user/account/
    ├── user/profile/
    └── error/

7.1 App.vue

<script setup>
import NavBar from '@/components/navbar/NavBar.vue'
</script>

<template>
  <NavBar>
    <RouterView />
  </NavBar>
</template>

RouterView 是页面出口，当前路由匹配到的组件会渲染在这里。

---

八、Vue Router 路由配置

import { createRouter, createWebHistory } from 'vue-router'
import HomepageIndex from '@/views/homepage/HomepageIndex.vue'
import FriendIndex from '@/views/friend/FriendIndex.vue'
import CreateIndex from '@/views/create/CreateIndex.vue'
import LoginIndex from '@/views/user/account/LoginIndex.vue'
import RegisterIndex from '@/views/user/account/RegisterIndex.vue'
import ProfileIndex from '@/views/user/profile/ProfileIndex.vue'
import NotFoundIndex from '@/views/error/NotFoundIndex.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    { path: '/', component: HomepageIndex, name: 'homepage-index' },
    { path: '/friend', component: FriendIndex, name: 'friend-index' },
    { path: '/create', component: CreateIndex, name: 'create-index' },
    { path: '/login', component: LoginIndex, name: 'login-index' },
    { path: '/register', component: RegisterIndex, name: 'register-index' },
    { path: '/user/profile', component: ProfileIndex, name: 'user-profile-index' },
    { path: '/:pathMatch(.*)*', component: NotFoundIndex, name: 'not-found' },
  ],
})

export default router

8.1 404 路由易错点

正确写法：

{ path: '/:pathMatch(.*)*', component: NotFoundIndex }

错误写法：

{ path: '/:pathMatch(*)*', component: NotFoundIndex }

错误原因：(*) 不是合法正则，会导致路由文件解析失败，前端白屏。

---

九、导航栏组件设计

9.1 导航栏功能

导航栏包含：

• 左侧菜单按钮；
• 项目标题；
• 搜索框；
• 登录 / 注册 / 用户头像菜单；
• 侧边栏路由入口：首页、好友、创作。

9.2 RouterLink

RouterLink 用于前端无刷新跳转：

<RouterLink :to="{ name: 'homepage-index' }" active-class="menu-focus">
  首页
</RouterLink>

重点：

• to 指定跳转目标；
• name 必须和路由表中一致；
• active-class 用于当前页面高亮。

9.3 Tailwind / DaisyUI 常用类

类	含义
flex	弹性布局
justify-center	主轴居中
items-center	交叉轴居中
w-60	宽度，Tailwind 中 1 单位通常为 0.25rem
px-2	x 方向内边距
mx-2	x 方向外边距
btn	DaisyUI 按钮
navbar	DaisyUI 导航栏
drawer	DaisyUI 抽屉侧边栏

---

十、前后端整合流程

10.1 开发环境

开发时通常启动两个服务：

# 后端
cd backend
python manage.py runserver

# 前端
cd frontend
npm run dev

访问：

• 前端：http://localhost:5173
• 后端：http://127.0.0.1:8000

此时前后端通过 CORS 通信。

10.2 生产 / 打包环境

cd frontend
npm run build

构建后：

1. Vue 源码被编译成 JS、CSS、图片等静态资源；
2. 静态资源输出到 Django 的 static/frontend；
3. Django 返回 index.html；
4. 浏览器加载静态资源并启动 Vue 应用。

10.3 完整访问生命周期

1. 用户访问 http://127.0.0.1:8000/；
2. Django 路由匹配根路径，返回 index.html；
3. 浏览器解析 HTML，请求 JS / CSS 静态资源；
4. Vue 应用启动，接管页面渲染；
5. 用户操作页面时，Vue 调用 Django API 获取数据；
6. Django 查询数据库或调用大模型服务，返回 JSON / SSE 数据。

---

十一、Git 忽略文件建议

__pycache__/
*.py[cod]
.venv/
.env
*.env
node_modules/
dist/
.idea/
.vscode/
db.sqlite3
media/
static/frontend/
frontend/public/vad/

不要提交：

• API Key；
• 本地数据库；
• 用户上传文件；
• 虚拟环境；
• node_modules；
• 大体积模型文件。

---

十二、本节易错点

12.1 项目路径不要包含中文

部分 Python 包或前端工具在中文路径下可能出现编码或路径解析问题。

12.2 CORS 与 Cookie

如果前端需要携带 Cookie：

前端：

axios.create({
  withCredentials: true,
})

后端：

CORS_ALLOW_CREDENTIALS = True

12.3 static 和 media 不要混淆

• 前端打包产物属于 static；
• 用户头像、角色图属于 media。

12.4 前端路由刷新 404

需要 Django 添加兜底：

re_path(r'^(?!media/|static/|assets/).*$', index)

12.5 路由名称要统一

RouterLink 中的 name 必须和 router/index.js 中完全一致，否则点击后无法跳转。

---

十三、小结

本节完成了项目基础骨架：

• Django 提供后端 API、数据库、静态资源服务；
• Vue 负责 SPA 页面和用户交互；
• Vite 负责开发热更新与生产打包；
• Tailwind CSS + DaisyUI 提供 UI 能力；
• Vue Router 负责前端页面切换；
• Django 的兜底路由解决 History 模式刷新问题。

后续所有模块都围绕这套结构继续扩展：登录模块负责用户身份，角色模块负责内容生产，信息流负责展示，聊天模块负责 AI 交互，语音模块负责自然交互体验。

---

十四、新手跟做路线

如果你是第一次做这种项目，可以按下面顺序操作，不要一开始就关注所有配置细节。

14.1 第一步：确认后端能跑

进入后端目录：

cd backend
python manage.py runserver

看到类似下面内容就说明 Django 启动成功：

Starting development server at http://127.0.0.1:8000/

浏览器打开：

http://127.0.0.1:8000/

如果能看到页面或前端入口，说明后端服务正常。

14.2 第二步：确认前端能跑

进入前端目录：

cd frontend
npm install
npm run dev

浏览器打开：

http://localhost:5173/

如果页面可以显示，并且修改 Vue 文件后页面自动刷新，说明 Vite 开发服务器正常。

14.3 第三步：确认前后端能通信

在浏览器按 F12 打开开发者工具，切换到 Network。

刷新页面后观察：

• 是否有请求发往 http://127.0.0.1:8000；
• 状态码是否为 200；
• 如果是 404，优先检查后端路由；
• 如果是 CORS 错误，优先检查 django-cors-headers 配置。

---

十五、新手常见问题排查

15.1 运行 python manage.py runserver 报错

常见原因：

1. 没进入 backend 目录；
2. 虚拟环境没激活；
3. 依赖没安装；
4. settings.py 配置写错；
5. 数据库迁移没执行。

排查顺序：

python --version
pip list
python manage.py check
python manage.py migrate
python manage.py runserver

15.2 npm run dev 报错

常见原因：

1. 没安装 Node.js；
2. 没执行 npm install；
3. node_modules 缺失；
4. 端口被占用；
5. package.json 依赖版本冲突。

排查：

node -v
npm -v
npm install
npm run dev

15.3 页面白屏

检查顺序：

1. 浏览器 Console 是否有红色报错；
2. 路由配置是否写错；
3. 组件导入路径是否大小写一致；
4. App.vue 是否正确包含 RouterView；
5. 后端返回的 index.html 是否加载到了 JS 文件。

15.4 访问前端路由刷新 404

例如刷新：

http://127.0.0.1:8000/user/profile/

如果后端返回 404，说明 Django 没有把这个路径交给 Vue，需要检查：

re_path(r'^(?!media/|static/|assets/).*$', index)

---

十六、本节复习问题

1. backend 和 frontend 分别负责什么？
2. static 和 media 有什么区别？
3. 为什么 Vue Router 的 History 模式刷新时需要 Django 兜底路由？
4. npm run dev 和 npm run build 有什么区别？
5. 为什么不能把 .env、node_modules、用户上传文件提交到 Git？
6. RouterLink 和普通 <a> 标签有什么区别？
7. 为什么项目要使用组件化开发？

---

十七、核心页面请求 / 响应示例

基础环境这一节还没有复杂业务接口，但有两个非常重要的访问路径。

17.1 访问首页入口

GET /

成功响应通常是 HTML：

<div id="app"></div>
<script type="module" src="/src/main.js"></script>

它的作用是把浏览器交给 Vue 接管。

17.2 访问静态资源

GET /assets/index.js
GET /assets/index.css

成功响应：

JavaScript 或 CSS 文件内容

如果这里 404，页面通常会白屏。

17.3 访问用户上传资源

GET /media/user/photo/alice.png

成功响应：

图片二进制内容

浏览器会把它显示成图片。

---

十八、关键代码逐行解释示例

18.1 Vue 应用入口

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App).use(router).mount('#app')

逐行解释：

代码	新手解释
import { createApp } from 'vue'	从 Vue 中导入创建应用的方法
import App from './App.vue'	导入根组件，整个页面从这里开始
import router from './router'	导入前端路由配置
createApp(App)	创建一个 Vue 应用实例
.use(router)	给 Vue 应用安装路由能力
.mount('#app')	把 Vue 应用挂载到 HTML 中 id 为 app 的元素上

18.2 Django 兜底路由

re_path(r'^(?!media/|static/|assets/).*$', index)

逐段解释：

代码	新手解释
re_path	使用正则表达式匹配 URL
^(?!...)	负向排除，表示不要匹配某些开头
media/	排除用户上传文件路径
static/	排除后端静态文件路径
assets/	排除前端打包资源路径
.*$	匹配其他所有路径
index	返回前端入口页面，让 Vue Router 接管

---

十九、Vue 组件数据传递图

main.js
  ↓ 创建 Vue 应用
App.vue
  ↓ 放置 RouterView
router/index.js
  ↓ 根据 URL 决定显示哪个页面
NavBar.vue
  ↓ 点击 RouterLink
HomePage.vue / FriendPage.vue / ProfilePage.vue

导航栏状态变化：

Pinia user store
  ↓ 提供登录状态
NavBar.vue
  ├── 未登录：显示登录 / 注册按钮
  └── 已登录：显示头像 / 用户菜单

---

二十、后端入口视图处理流程

浏览器访问 / 或 /friend/ 等前端路由
  ↓
Django URL 匹配
  ↓
如果是 /media/、/static/、/assets/，返回对应资源
  ↓
如果不是资源路径，进入兜底路由
  ↓
index 视图返回 index.html
  ↓
浏览器加载 JS 和 CSS
  ↓
Vue Router 根据当前 URL 渲染对应页面

---

二十一、小练习与自测答案

练习 1

问题：为什么刷新 /friend/ 页面时不能直接让 Django 查找一个后端页面？

答案：/friend/ 是 Vue Router 的前端路由，不是 Django 业务接口。刷新时 Django 需要返回同一个 index.html，再由 Vue 根据 URL 渲染好友页面。

练习 2

问题：为什么兜底路由要排除 /media/ 和 /assets/？

答案：这些路径是真实资源路径。如果不排除，浏览器请求图片或 JS 文件时会拿到 index.html，导致图片无法显示或页面白屏。

练习 3

问题：为什么导航栏适合做成公共组件？

答案：导航栏在多个页面都会出现。做成组件后，只维护一份代码，所有页面都能复用。