配置环境、创建项目与导航栏一、目标完成项目从 0 到 1 的搭建配置 Python、Node.js、Git、IDE 等开发环境创建 Django 后端项目与 Vue 3 前端项目配置 DRF、JWT、CORS、静态文件和媒体文件使用 Tailwind CSS DaisyUI 搭建基础导航栏理解开发环境与生产部署环境的区别完成前端打包到 Django 后端的基础整合。本节是整个 AgentTalk 项目的地基后续登录、角色、聊天、语音模块都建立在这里的前后端工程结构之上。二、开发环境配置2.1 Python 与虚拟环境后端使用 Django因此需要安装 Python并建议使用虚拟环境隔离依赖。python-mvenv .venv .venv\Scripts\activateLinux / macOSpython-mvenv .venvsource.venv/bin/activate虚拟环境的作用每个项目拥有独立依赖避免全局 Python 包版本冲突方便通过requirements.txt复现环境。2.2 Node.js 与 npm前端使用 Vue 3 Vite需要 Node.js 提供构建工具运行环境。安装地址https://nodejs.org/安装时建议勾选Add to PATH。更新 npmnpminstall-gnpmlatestNode.js 在本项目中的作用运行 Vite 开发服务器管理 Vue、Pinia、DaisyUI 等前端依赖执行npm run build将 Vue 源码打包成浏览器可运行的静态文件。2.3 Git 与 SSH安装 Githttps://gitforwindows.org/生成 SSH Keyssh-keygen常用 Git 命令gitstatusgitadd.gitcommit-m提交说明gitpushgitpullgitclonerepo-url重点理解git status查看工作区与暂存区状态git add将修改加入暂存区git commit生成本地提交记录git push推送到远程仓库.gitignore忽略不应该提交的文件如虚拟环境、数据库、环境变量、打包产物。2.4 PyCharm / IDE 配置如果使用 PyCharm安装中文插件Settings - Plugins - Marketplace开启 Django 支持Settings - Languages Frameworks - Django配置 Django project root、settings、manage.py将backend目录标记为 Sources Root避免无法识别web模块。三、创建 Django 后端3.1 创建项目与应用django-admin startproject backendcdbackend 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 安装后端依赖pipinstalldjango pipinstalldjangorestframework pipinstalldjangorestframework-simplejwt pipinstalldjango-cors-headers pipinstallpillow依赖说明包作用django后端 Web 框架djangorestframework编写 REST APIdjangorestframework-simplejwtJWT 登录认证django-cors-headers处理跨域pillow处理图片上传字段四、配置 Django settings.py4.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_ZONEAsia/ShanghaiUSE_TZTrue4.4 静态文件与媒体文件STATIC_URLstatic/STATICFILES_DIRS[BASE_DIR/static,]MEDIA_URL/media/MEDIA_ROOTBASE_DIR/mediastatic 与 media 区别类型含义示例static开发者提供的静态资源JS、CSS、前端打包文件media用户上传的动态文件头像、角色背景图4.5 JWT 配置fromdatetimeimporttimedelta REST_FRAMEWORK{DEFAULT_AUTHENTICATION_CLASSES:(rest_framework_simplejwt.authentication.JWTAuthentication,),}SIMPLE_JWT{ACCESS_TOKEN_LIFETIME:timedelta(hours2),REFRESH_TOKEN_LIFETIME:timedelta(days7),ROTATE_REFRESH_TOKENS:True,BLACKLIST_AFTER_ROTATION:True,AUTH_HEADER_TYPES:(Bearer,),}4.6 CORS 配置CORS_ALLOW_CREDENTIALSTrueCORS_ALLOWED_ORIGINS[http://localhost:5173,http://127.0.0.1:5173,]CORS_ALLOW_CREDENTIALS True用于允许跨域请求携带 Cookie。五、配置后端路由与前端入口5.1 项目根路由backend/backend/urls.pyfromdjango.contribimportadminfromdjango.urlsimportpath,includefromdjango.confimportsettingsfromdjango.conf.urls.staticimportstatic urlpatterns[path(admin/,admin.site.urls),path(,include(web.urls)),]ifsettings.DEBUG:urlpatternsstatic(/media/,document_rootsettings.MEDIA_ROOT)5.2 web 子路由backend/web/urls.pyfromdjango.urlsimportpath,re_pathfromweb.views.indeximportindex 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 创建项目npmcreate vuelatestcdfrontendnpminstall推荐选择Vue RouterPiniaESLint / Prettier 可按需要选择。6.2 安装 Tailwind CSS 与 DaisyUInpminstall-Dtailwindcss tailwindcss/vitenpminstall-Ddaisyui在frontend/src/assets/main.css中importtailwindcss;plugindaisyui;6.3 配置 Vite 打包输出frontend/vite.config.jsimport{fileURLToPath,URL}fromnode:urlimport{defineConfig}fromviteimportvuefromvitejs/plugin-vueimporttailwindcssfromtailwindcss/viteimportpathfrompathexportdefaultdefineConfig({plugins:[vue(),tailwindcss()],build:{outDir:path.resolve(__dirname,../backend/static/frontend),emptyOutDir:true,},resolve:{alias:{:fileURLToPath(newURL(./src,import.meta.url)),},},})这样执行npmrun 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.vuescript setup import NavBar from /components/navbar/NavBar.vue /script template NavBar RouterView / /NavBar /templateRouterView是页面出口当前路由匹配到的组件会渲染在这里。八、Vue Router 路由配置import{createRouter,createWebHistory}fromvue-routerimportHomepageIndexfrom/views/homepage/HomepageIndex.vueimportFriendIndexfrom/views/friend/FriendIndex.vueimportCreateIndexfrom/views/create/CreateIndex.vueimportLoginIndexfrom/views/user/account/LoginIndex.vueimportRegisterIndexfrom/views/user/account/RegisterIndex.vueimportProfileIndexfrom/views/user/profile/ProfileIndex.vueimportNotFoundIndexfrom/views/error/NotFoundIndex.vueconstroutercreateRouter({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},],})exportdefaultrouter8.1 404 路由易错点正确写法{path:/:pathMatch(.*)*,component:NotFoundIndex}错误写法{path:/:pathMatch(*)*,component:NotFoundIndex}错误原因(*)不是合法正则会导致路由文件解析失败前端白屏。九、导航栏组件设计9.1 导航栏功能导航栏包含左侧菜单按钮项目标题搜索框登录 / 注册 / 用户头像菜单侧边栏路由入口首页、好友、创作。9.2 RouterLinkRouterLink用于前端无刷新跳转RouterLink :to{ name: homepage-index } active-classmenu-focus 首页 /RouterLink重点to指定跳转目标name必须和路由表中一致active-class用于当前页面高亮。9.3 Tailwind / DaisyUI 常用类类含义flex弹性布局justify-center主轴居中items-center交叉轴居中w-60宽度Tailwind 中 1 单位通常为 0.25rempx-2x 方向内边距mx-2x 方向外边距btnDaisyUI 按钮navbarDaisyUI 导航栏drawerDaisyUI 抽屉侧边栏十、前后端整合流程10.1 开发环境开发时通常启动两个服务# 后端cdbackend python manage.py runserver# 前端cdfrontendnpmrun dev访问前端http://localhost:5173后端http://127.0.0.1:8000此时前后端通过 CORS 通信。10.2 生产 / 打包环境cdfrontendnpmrun build构建后Vue 源码被编译成 JS、CSS、图片等静态资源静态资源输出到 Django 的static/frontendDjango 返回index.html浏览器加载静态资源并启动 Vue 应用。10.3 完整访问生命周期用户访问http://127.0.0.1:8000/Django 路由匹配根路径返回index.html浏览器解析 HTML请求 JS / CSS 静态资源Vue 应用启动接管页面渲染用户操作页面时Vue 调用 Django API 获取数据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_CREDENTIALSTrue12.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 第一步确认后端能跑进入后端目录cdbackend python manage.py runserver看到类似下面内容就说明 Django 启动成功Starting development server at http://127.0.0.1:8000/浏览器打开http://127.0.0.1:8000/如果能看到页面或前端入口说明后端服务正常。14.2 第二步确认前端能跑进入前端目录cdfrontendnpminstallnpmrun 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 报错常见原因没进入backend目录虚拟环境没激活依赖没安装settings.py配置写错数据库迁移没执行。排查顺序python--versionpip list python manage.py check python manage.py migrate python manage.py runserver15.2 npm run dev 报错常见原因没安装 Node.js没执行npm installnode_modules缺失端口被占用package.json依赖版本冲突。排查node-vnpm-vnpminstallnpmrun dev15.3 页面白屏检查顺序浏览器 Console 是否有红色报错路由配置是否写错组件导入路径是否大小写一致App.vue是否正确包含RouterView后端返回的index.html是否加载到了 JS 文件。15.4 访问前端路由刷新 404例如刷新http://127.0.0.1:8000/user/profile/如果后端返回 404说明 Django 没有把这个路径交给 Vue需要检查re_path(r^(?!media/|static/|assets/).*$,index)十六、本节复习问题backend和frontend分别负责什么static和media有什么区别为什么 Vue Router 的 History 模式刷新时需要 Django 兜底路由npm run dev和npm run build有什么区别为什么不能把.env、node_modules、用户上传文件提交到 GitRouterLink和普通a标签有什么区别为什么项目要使用组件化开发十七、核心页面请求 / 响应示例基础环境这一节还没有复杂业务接口但有两个非常重要的访问路径。17.1 访问首页入口GET /成功响应通常是 HTMLdividapp/divscripttypemodulesrc/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}fromvueimportAppfrom./App.vueimportrouterfrom./routercreateApp(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问题为什么导航栏适合做成公共组件答案导航栏在多个页面都会出现。做成组件后只维护一份代码所有页面都能复用。