企业官网建设流程全解析

Recipes 从源码搭建开发环境指南：Django 5 后端与 Vue 3 前端的本地开发、测试与 Docker 构建

【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes

导读

本文是 Recipes（Tandoor）项目的开发环境搭建实战指南，面向希望参与开源贡献或进行二次开发的工程师。Recipes 采用Django（后端）与 Vue.js（前端）的双栈架构，本文将从 Devcontainer 一键容器化、Django 后端本地启动、Vue 3 前端热重载开发，以及从源码构建 Docker 镜像四个维度，结合仓库内的真实配置与源码，给出可直接复制的命令与注意事项。读完本文，你将能独立在本机跑通完整的开发环境，并理解前后端联动的底层原理。

开发环境概览：为什么这个项目"稍微有点乱"

Recipes 是一个典型的前后端分离但又由 Django 统一服务的混合架构：后端基于 Django 框架开发，负责模型、API、权限与业务逻辑；前端则使用 Vue.js（当前仓库为vue3/目录）构建，并通过 django-vite 插件与 Django 集成。

正如仓库 docs/contribute/installation.md 开篇所提示的那样，这种组合在开发环境上"有点凌乱"（a little messy）：你需要同时维护 Python 依赖与 JavaScript 依赖两条依赖线，且 Django 能否正确找到前端资源，取决于 Vite 开发服务器是否处于运行状态。理解了这一点，后续所有步骤就都有了清晰的主线。

从仓库证据看：

• Python 侧依赖清单位于 requirements.txt，其中 Django 版本为Django==5.2.16，还包含djangorestframework、django-vite、drf-spectacular等核心依赖；
• 前端侧依赖清单位于 vue3/package.json，包含 Vue 3、Vuetify、Pinia、Vue Router、vite-plugin-pwa 等；
• Django 与 Vite 的衔接配置位于 recipes/settings.py 的DJANGO_VITE字典中。

方式一：Devcontainer 容器化开发（推荐）

仓库为开发者准备了开箱即用的Devcontainer（开发容器）配置，它基于 containers.dev 规范，专为VSCode优化，理论上也兼容其他支持 Devcontainer 的编辑器。

使用步骤非常简单：

1. 克隆本仓库到本地；
2. 在 VSCode 中打开该目录；
3. 通过命令面板（Command Palette）执行Dev Containers: Reopen in container，VSCode 会自动构建并进入开发容器。

容器启动后，你可以在其中做几乎所有开发相关的事情：启动 Django 开发服务器、启动 Vue.js 开发服务器、运行 Python 测试等。你可以通过 VSCode 的任务（Tasks）触发，也可以手动执行下文各技术小节中的命令。

什么时候需要重建容器？根据原文档说明：

• 当你修改了 Python 依赖（requirements.txt）或操作系统级软件包时，需要重建容器；
• 如果修改的是 OS 包需求，则需要同时更新主 Dockerfile 与.devcontainer/Dockerfile两处。

需要说明的是：当前仓库快照中未包含.devcontainer/目录（其内容通常在发布包中独立提供），上述两文件协同更新的原则来自原文档说明，实际操作以你克隆的完整仓库为准。

方式二：Django 后端本地开发

Recipes 的后端是标准 Django 应用，入口为仓库根目录的 manage.py。官方 Django 文档对框架本身的入门讲解已经非常详尽，这里只聚焦本项目需要的最小必要步骤。

1. 克隆仓库并准备 Python 环境

将仓库克隆到任意本地目录，并为你的操作系统安装 Python。原文档建议使用Python 3.10 或以上版本；而当前仓库的 Dockerfile 使用的是python:3.13-alpine3.23，因此使用 3.10 及以上版本均可满足要求。

建议（可选但推荐）为项目创建独立的 Python 虚拟环境，避免污染全局环境：

python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate

2. 安装 Python 依赖

在仓库根目录执行：

pip install -r requirements.txt

requirements.txt中不仅包含运行时依赖，还包含# Development注释段以下的开发依赖，如pytest、pytest-django、flake8、yapf、autopep8等，这意味着一次安装即可同时获得开发与测试所需的全部工具。

3. 执行数据库迁移

python manage.py migrate

这一步会创建并初始化数据库结构。默认情况下，项目直接使用SQLite数据库，无需任何额外配置。

4. 启动开发服务器

python manage.py runserver

启动后即可通过 Django 自带的开发服务器访问应用。

关键点：无需设置任何环境变量

这是本项目的显著便利之处。原文档明确说明：

没有任何必要设置环境变量。默认情况下使用一个简单的 SQLite 数据库，所有设置都从默认值填充。

从源码可以得到印证：在 recipes/settings.py 的数据库设置逻辑中，当未提供DATABASE_URL/DB_ENGINE等环境变量时，引擎默认回退到django.db.backends.sqlite3，数据库文件名为db.sqlite3；manage.py 也会在未指定时默认使用recipes.settings配置模块。也就是说，克隆 → 装依赖 → migrate → runserver四步即可让后端跑起来。

提示：默认的runserver配置仅适用于本地开发。生产环境下的数据库、密钥与静态文件策略请参考 docs/install 系列文档，本文不展开。

方式三：Vue 3 前端开发（热重载）

Recipes 的前端位于 vue3/ 目录，使用 Vite 作为构建工具与开发服务器。如果你想修改前端页面，需要按以下步骤操作。

前提：选择一个 JavaScript 包管理器

你需要一个 Node.js 包管理器，原文档以yarn为例。当前仓库同时提供yarn.lock与vue3/package-lock.json，说明 yarn 与 npm 均可使用，下文以 yarn 为例。

1. 安装前端依赖

cd vue3 yarn install

vue3/package.json中的依赖包含 Vue 3、Vuetify 3、Pinia、Vue Router、vue-i18n、mavon-editor 等，规模较大，安装可能需要一点时间。

2. 启动 Vite 开发服务器

yarn serve

注意：原文档中的命令是yarn serve，而当前仓库 vue3/package.json 中定义的脚本为dev（即vite）、build、preview，未包含serve脚本。因此在本仓库的实际环境中，对应命令应为yarn dev（直接运行 Vite）。两处指的是同一个开发服务器，只是脚本命名随版本演变而调整，使用时以当前仓库package.json为准。

该开发服务器提供**热重载（Hot Reload）**能力，修改代码后页面即时刷新，方便快速迭代。

3. 先启动 Vite，再启动 Django —— 顺序不可颠倒！

这是整个开发环境中最容易被忽略、也最关键的一个细节。原文档用danger级别的警告专门强调：

Vite 开发服务器必须在 Djangorunserver命令之前启动，否则 Django 将无法识别它，并回退到使用构建后的静态文件。

从源码可以解释其原理。在 recipes/settings.py 中，DJANGO_VITE配置定义：

• dev_server_port: 5173
• dev_server_host: localhost（可用DJANGO_VITE_DEV_SERVER_HOST环境变量覆盖）
• static_url_prefix: 'vue3'
• manifest_path指向cookbook/static/vue3/manifest.json

关键逻辑在于紧随其后的启动探测代码：Django 启动时会尝试用 socket 连接localhost:5173，如果连接成功且DEBUG=True，则将dev_mode置为True（输出 "Vite Dev Server is running"），此后 Django 就会从 Vite 开发服务器拉取前端资源并启用热重载；反之则打印 "Running django-vite in production mode (no HMR)"，回退到读取已构建的 manifest 与静态文件。

因此，正确的前后端联调顺序是：

# 终端 1：先启动前端 cd vue3 yarn dev # 终端 2：再启动后端 python manage.py runserver

对应的，vue3/vite.config.ts 中开发服务器监听0.0.0.0，origin固定为http://localhost:5173，与 Django 侧的探测端口完全一致。

4. 不想改前端？一次性构建静态资源即可

如果你只关心后端开发、不打算修改前端页面，就不需要常驻 Vite 服务器，只需构建一次前端产物：

cd vue3 yarn build

之后可能需要执行collectstatic让 Django 收集静态文件：

python manage.py collectstatic

vue3/package.json中build脚本为vite build --emptyOutDir，而 vue3/vite.config.ts 将构建输出目录设置为../cookbook/static/vue3/，并同时生成manifest.json—— 这正是DJANGO_VITE中manifest_path所指向的文件，Django 依赖它完成资源版本映射。

补充：运行测试与代码检查

完成上述任一种后端环境搭建后，你可以直接运行项目的测试套件，验证环境是否健康：

pytest

根据 pytest.ini 的配置，测试默认使用recipes.test_settings设置模块，测试路径为cookbook/tests，并默认启用-n auto多进程并行与覆盖率统计（报告输出到docs/reports/目录）。仓库的 cookbook/tests 下覆盖了 API、集成、解析器、搜索等大量用例，可作为了解项目行为的活文档。

如果参与代码贡献，还需注意项目配置了flake8、yapf、isort等检查工具（见 requirements.txt 的 Development 段），具体规范与编辑器配置可参考 docs/contribute/guidelines.md、docs/contribute/vscode.md 与 docs/contribute/pycharm.md。

从源码构建 Docker 镜像

如果你想从源码构建自己的 Docker 镜像，步骤与"构建前端"类似——必须先构建 Vue 3 产物，因为镜像构建过程会直接使用前端构建结果。

构建步骤

# 1. 进入前端目录并安装依赖 cd vue3 yarn install # 2. 构建静态文件供 Django 使用 yarn build # 3. 回到仓库根目录，构建镜像（自行替换 tag 与 version） cd .. docker build -t ${tag}:${version} .

为什么这里不需要手动 collectstatic？

这与方式二中的本地构建流程不同。原文档指出：Docker 场景下不需要手动执行collectstatic，因为Dockerfile的入口脚本会在容器启动（docker run）时自动完成静态文件收集。

从仓库源码可以得到完整印证：

• Dockerfile 基于python:3.13-alpine3.23，安装 nginx、nodejs、npm 等运行所需组件，并把requirements.txt中# Development段之后的开发依赖剔除后安装到独立 venv；
• 容器入口为 boot.sh，由ENTRYPOINT ["/sbin/tini", "--", "/opt/recipes/boot.sh"]指定。boot.sh中依次执行：通过envsubst渲染 nginx 配置、启动 nginx、等待数据库就绪、执行python manage.py migrate、执行python manage.py collectstatic --noinput --clear，最后以 gunicorn 启动recipes.wsgi。

也就是说，docker build只负责把"已构建的前端产物 + 后端代码 + 依赖"打进镜像，而migrate、collectstatic等初始化动作全部推迟到容器首次启动时由boot.sh完成。此外，boot.sh还支持通过PLUGINS_BUILD=1在启动时执行python plugin.py重新构建插件前端资源，这也解释了为什么前端产物必须在镜像构建前准备好。

生产容器运行的最小前提

虽然开发环境"零环境变量"即可运行，但容器生产运行则相反：boot.sh会强制检查SECRET_KEY（或SECRET_KEY_FILE）、PostgreSQL 场景下的POSTGRES_PASSWORD等必需变量，缺少时打印警告甚至退出。这是开发环境与生产容器的重要差异，部署细节可参考 docs/install/docker.md。

常见问题排查

结语

本文完整还原了 docs/contribute/installation.md 的开发环境搭建流程，并基于仓库源码补充了前后端联动的底层机制：DJANGO_VITE的启动探测逻辑、Vite 构建产物与 manifest 的衔接方式，以及boot.sh在容器生命周期中承担的初始化职责。无论你选择 Devcontainer、纯本地 Django + Vue 双进程开发，还是从源码构建 Docker 镜像，只要把握住"Vite 先行、依赖重建、静态收集"三个关键点，就能顺利跑通 Recipes 的整套开发环境，进入实际的代码贡献与二次开发环节。

【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes