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导读本文是 RecipesTandoor项目的开发环境搭建实战指南面向希望参与开源贡献或进行二次开发的工程师。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 版本为Django5.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 的编辑器。使用步骤非常简单克隆本仓库到本地在 VSCode 中打开该目录通过命令面板Command Palette执行Dev Containers: Reopen in containerVSCode 会自动构建并进入开发容器。容器启动后你可以在其中做几乎所有开发相关的事情启动 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\activate2. 安装 Python 依赖在仓库根目录执行pip install -r requirements.txtrequirements.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.sqlite3manage.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 installvue3/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: 5173dev_server_host: localhost可用DJANGO_VITE_DEV_SERVER_HOST环境变量覆盖static_url_prefix: vue3manifest_path指向cookbook/static/vue3/manifest.json关键逻辑在于紧随其后的启动探测代码Django 启动时会尝试用 socket 连接localhost:5173如果连接成功且DEBUGTrue则将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.0origin固定为http://localhost:5173与 Django 侧的探测端口完全一致。4. 不想改前端一次性构建静态资源即可如果你只关心后端开发、不打算修改前端页面就不需要常驻 Vite 服务器只需构建一次前端产物cd vue3 yarn build之后可能需要执行collectstatic让 Django 收集静态文件python manage.py collectstaticvue3/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_BUILD1在启动时执行python plugin.py重新构建插件前端资源这也解释了为什么前端产物必须在镜像构建前准备好。生产容器运行的最小前提虽然开发环境零环境变量即可运行但容器生产运行则相反boot.sh会强制检查SECRET_KEY或SECRET_KEY_FILE、PostgreSQL 场景下的POSTGRES_PASSWORD等必需变量缺少时打印警告甚至退出。这是开发环境与生产容器的重要差异部署细节可参考 docs/install/docker.md。常见问题排查现象可能原因解决办法Django 页面加载不到新改的前端样式/组件Vite 开发服务器未启动或启动顺序晚于runserver按先yarn dev、后runserver的顺序重启两者确认 settings 中dev_modeTrueyarn serve报找不到脚本当前仓库package.json中脚本名为dev改用yarn dev修改了requirements.txt后容器内不生效容器需要重建执行Dev Containers: Rebuild Container前端构建产物不更新未重新执行yarn build或未执行collectstatic先yarn build再python manage.py collectstatic测试报错提示缺少数据库尚未执行迁移执行python manage.py migrate结语本文完整还原了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Recipes 从源码搭建开发环境指南：Django 5 后端与 Vue 3 前端的本地开发、测试与 Docker 构建
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导读本文是 RecipesTandoor项目的开发环境搭建实战指南面向希望参与开源贡献或进行二次开发的工程师。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 版本为Django5.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 的编辑器。使用步骤非常简单克隆本仓库到本地在 VSCode 中打开该目录通过命令面板Command Palette执行Dev Containers: Reopen in containerVSCode 会自动构建并进入开发容器。容器启动后你可以在其中做几乎所有开发相关的事情启动 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\activate2. 安装 Python 依赖在仓库根目录执行pip install -r requirements.txtrequirements.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.sqlite3manage.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 installvue3/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: 5173dev_server_host: localhost可用DJANGO_VITE_DEV_SERVER_HOST环境变量覆盖static_url_prefix: vue3manifest_path指向cookbook/static/vue3/manifest.json关键逻辑在于紧随其后的启动探测代码Django 启动时会尝试用 socket 连接localhost:5173如果连接成功且DEBUGTrue则将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.0origin固定为http://localhost:5173与 Django 侧的探测端口完全一致。4. 不想改前端一次性构建静态资源即可如果你只关心后端开发、不打算修改前端页面就不需要常驻 Vite 服务器只需构建一次前端产物cd vue3 yarn build之后可能需要执行collectstatic让 Django 收集静态文件python manage.py collectstaticvue3/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_BUILD1在启动时执行python plugin.py重新构建插件前端资源这也解释了为什么前端产物必须在镜像构建前准备好。生产容器运行的最小前提虽然开发环境零环境变量即可运行但容器生产运行则相反boot.sh会强制检查SECRET_KEY或SECRET_KEY_FILE、PostgreSQL 场景下的POSTGRES_PASSWORD等必需变量缺少时打印警告甚至退出。这是开发环境与生产容器的重要差异部署细节可参考 docs/install/docker.md。常见问题排查现象可能原因解决办法Django 页面加载不到新改的前端样式/组件Vite 开发服务器未启动或启动顺序晚于runserver按先yarn dev、后runserver的顺序重启两者确认 settings 中dev_modeTrueyarn serve报找不到脚本当前仓库package.json中脚本名为dev改用yarn dev修改了requirements.txt后容器内不生效容器需要重建执行Dev Containers: Rebuild Container前端构建产物不更新未重新执行yarn build或未执行collectstatic先yarn build再python manage.py collectstatic测试报错提示缺少数据库尚未执行迁移执行python manage.py migrate结语本文完整还原了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考