第一次给 Dify 提 PR 的完整指南从 Issue 到 PR 与本地开发环境搭建教程【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify这份 Dify 开源贡献指南带你走完一条真实路径先把本地开发环境搭起来后端 uv 前端 pnpm再挑一个合适的贡献方向然后把 Bug 报告、功能请求、PR 提交串成一条连续流程最后用仓库自带的测试命令做完合并前自查。照着做你第一次给 Dify 提 PR 时不会再卡在环境怎么跑、测试怎么测上。️ 先把本地开发环境跑起来Dify 主仓库由三部分构成api/ 是 Python 后端web/ 是前端docker/ 提供本地开发用的中间件PostgreSQL、Redis、Weaviate。下图是仓库里给出的本地服务拓扑搭完环境后你跑的就是这套东西后端四个脚本走完全程自 v1.3.0 起后端包管理器从 poetry 换成了uvapi/ 的所有开发命令都围绕它。仓库在 dev/ 目录放了一组脚本路径按脚本自身位置解析在任何目录执行都可以./dev/setup # 拷贝 .env 文件 安装前后端依赖 ./dev/start-docker-compose # 启动中间件PostgreSQL / Redis / Weaviate ./dev/start-api # 启动后端先自动执行数据库迁移 ./dev/start-web # 启动前端 ./dev/start-worker # 启动 worker异步任务与定时任务 ./dev/start-beat # 可选Celery Beat定时调度装完跑起来后打开http://localhost:3000完成初始化。有两个容易踩的坑提前说api/.env里的SECRET_KEY必须生成一个随机值别用默认值sed -i /^SECRET_KEY/c\SECRET_KEY$(openssl rand -base64 42) .env前后端如果跑在不同子域要把COOKIE_DOMAIN设成站点顶级域名否则认证 Cookie 共享不了。前端从仓库根目录装依赖前端是 Next.js 应用默认本地开发服务器是 vinext。注意 JavaScript 依赖统一由仓库根目录的工作区文件管理package.json、pnpm-lock.yaml、pnpm-workspace.yaml所以安装命令在根目录执行不是cd webpnpm install # 根目录执行装全部 JS 依赖 cp web/.env.example web/.env.local # 创建本地环境变量 pnpm dev # 启动默认开发栈vinext 本地 API 代理web/.env.local里重点核对两个前缀变量NEXT_PUBLIC_API_PREFIX和NEXT_PUBLIC_PUBLIC_API_PREFIX要指向你的后端 API 地址路由归属定义在 web/dev-proxy.config.ts。改web/app下的文件时页面会自动热更新前端贡献基本就在这个目录里发生。 决定你要做什么三个贡献入口环境能跑了下一个问题是改哪里。先看一眼 images/describe.png 这样的界面截图——这就是你要改动的产品本体Dify 的贡献入口分三条路别走错仓库改主仓库核心功能、Bug 修复、前后端代码。从带good first issue标签的开放 Issue 里挑一个入门任务这是官方给新手指的路。加新模型运行时 / 新工具这类东西不进主仓库PR 要提到独立的插件仓库dify-plugins。主仓库 api/core/plugin/ 里只是插件运行时与插件服务端的通信层不是模型和工具的实现。修现有插件 / 更新模型运行时提到官方插件仓库dify-official-plugins。不管你走哪条路都记住一件事PR 描述里要关联一个已存在的 Issue没有就先开一个。这是后面流程的起点。 从 Issue 到 PR一条连续流程先写 Issue再写代码开 PR 之前先建一个 Issue 讨论你打算改什么。这一步不是形式主义——维护者可以在你动手前否决方向省掉你白改几天的风险。写 Bug 报告时Issue 里至少要有这几样清晰、有信息量的标题详细的问题描述含完整错误信息可复现步骤steps to reproduce期望行为后端问题必须附日志——用docker-compose logs导出这一条经常被漏截图或视频视情况附上功能请求则写标题、功能描述、使用场景use case、补充上下文或截图。维护者怎么排优先级你心里有数就行核心功能故障无法登录、应用不可用、安全漏洞最高优先处理最快非关键缺陷、性能改进中等优先错别字、界面小瑕疵低优先功能侧团队成员标记过的高优先级功能最靠前社区反馈看板上的热门请求居中非核心增强靠后有价值但不急的会进 Future-Feature然后走 PRFork 仓库为新改动建独立分支改代码改动影响了可观测行为、或有实质性回归风险时补上或更新测试本地确认既有测试通过PR 描述里用fixes #issue_number关联你的 Issue等合并关于测试的态度前端测试指南 web/docs/test.md 说得很直白测试保护的是可观测的契约——用户交互与 UI 状态、导航与持久化、用户能到达的加载/成功/错误/空状态、可复现的回归 Bug。文件存在所以要有测试覆盖率缺口所以补一个这类理由评审者不认。✅ PR 合并前的质量自查清单提交前把这套命令跑一遍全绿再开 PR。后端从仓库根目录make lint # 格式化 ruff 检查 架构导入检查等 make type-check # 类型检查pyrefly mypy make test # 单元测试 make test TARGET_TESTS./api/tests/unit_tests/ # 只跑指定路径在api/目录下也能跑 pytestuv run pytest tests/unit_tests/ # 仅单元测试 uv run pytest tests/integration_tests/ # 集成测试api/tests/下分三层unit_tests/、integration_tests/、test_containers_integration_tests/日常改动画圈到哪个就跑哪个。前端从web/目录vp test run --project unit # 单元测试happy-dom 环境 vp test run --project unit path/to/spec # 只跑指定 spec两个提醒项目用了 Vitevitest命令不可用测试一律走vp并且必须显式指定--project裸vp test会把所有注册项目包括 Browser Mode全跑起来慢且不是你想要的。动手改后端前顺手过一眼 api/AGENTS.md 的分层约定传输解析和序列化留在 controller编排逻辑放 service领域策略放core/或其领域归属模块配置统一走configs.dify_config出站 HTTP 走core.helper.ssrf_proxy请求/响应模型用 Pydantic v2。另外要改 controller schema 或SystemFeatureModel之前先读 api/controllers/API_SCHEMA_GUIDE.md。 下一步卡住了怎么办两个渠道直接在对应的 GitHub Issue 里提问或者进 Dify 官方 Discord 社区入口见仓库根目录 README.md 的 Community 部分。回头看你刚走完的路本地环境跑通 → 选一个 Issue → Issue 里讨论 → 改代码、补测试 → 跑完自查命令 →fixes #issue关联 Issue 开 PR。这就是给 Dify 提贡献的完整循环第二个 PR 会明显比第一个快。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考