Dify 开源贡献完整指南从领 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 为对象走一遍完整的开源贡献路径选对投给哪个仓库、写出能被受理的 Bug 报告和功能请求、在本地把 uv 后端与 pnpm 前端两套环境跑通、用仓库自带的测试与 lint 工具链做提交前自查最后按规范提交一个能被合并的 Pull RequestPR即代码合并请求。跟着做完你能独立完成从领一个good first issue到代码入库的全过程。第一步选对要投的仓库主仓库还是插件仓库贡献 Dify 之前先回答一个问题你的改动属于哪个仓库官方贡献指南 docs/zh-CN/CONTRIBUTING.md 给出三类入口主仓库dify平台自身的代码——前后端、RAG 管线、工作流引擎等。带good first issue标签的开放 Issue 基本都来自这里新手建议从它起步dify-plugins 仓库新的模型运行时让某个模型能被 Dify 调用的适配代码或新工具一律投到这里主仓库不收dify-official-plugins 仓库已有模型/工具的更新与 Bug 修复投给官方插件仓库。从源码结构就能看出分工主仓库里 api/core/plugin/ 只是插件的运行时与服务端通信层真正的模型适配和工具实现都在插件仓库。判断标准很简单——看代码归属不看文档指引投错仓库的 PR 会被直接打回。第二步先懂规则许可与行为准则动手前花十分钟读完两样东西能帮你避开大多数社区摩擦许可与贡献者协议见仓库根目录 LICENSE。你贡献的代码受其约束署名权等条款值得逐条看完行为准则Code of Conduct社区对 Issue、PR 和日常交流的言行规范核心是对事不对人。Dify 还有个鲜明的社区文化Issue 先行。官方 PR 流程明确要求在提交 PR 之前先创建 Issue 讨论你要做的修改。这不是官僚流程——大改动的方向没对齐代码写得再好也可能白做。改个小错别字可以省掉讨论但涉及行为变化的改动先把 Issue 开出来。第三步写出能被受理的 IssueIssue 写得含糊是最常见的石沉大海原因。下面两种类型各有硬性要素照着清单写就不会被要求补料。Bug 报告日志是后端的硬门槛一份能受理的 Bug 报告必须包含清晰描述性的标题别写出错了写导入 Notion 文档报 500详细描述与完整错误信息复现步骤一步步能照着操作预期行为你期望发生什么日志——后端问题必须附上文档专门加粗强调日志可用docker-compose logs获取截图或视频如适用。官方优先级口径可压缩成三档核心功能故障登录失败、应用不可用、安全漏洞算紧急一般缺陷和性能问题算中等错别字、界面混乱但能用这类算低优先级。功能请求场景比功能本身更重要功能请求的四要素清晰描述性的标题功能的详细描述使用场景谁、在什么情况下、要解决什么问题——这是排期时最重要的依据其他上下文或截图。优先级四档被团队标记高优的功能走高优先级社区反馈看板里的热门请求走中优先级非核心小增强走低优先级有价值但不紧急的归入未来特性。第四步本地环境 8 步跑通uv 后端加 pnpm 前端dev/ 目录下的脚本是整个本地开发流程的入口它们相对自身位置解析路径在任何目录执行都可以。完整说明见 api/README.md 和 web/README.md这里只保留你要敲的命令和两个易错点。后端dev 脚本 uv 中间件自 v1.3.0 起Dify 后端用uv一个极快的 Python 包管理器替代了早期的 poetry管理依赖。按顺序执行./dev/setup # 拷 env 文件并安装前后端依赖 ./dev/start-docker-compose # 启动 PostgreSQL / Redis / Weaviate ./dev/start-api # 先跑数据库迁移再启动 API ./dev/start-web # 启动前端 ./dev/start-worker # Celery worker异步与定时任务 ./dev/start-beat # 可选Celery Beat 定时调度中间打开浏览器访问http://localhost:3000完成应用初始化。环境上有两个必须处理的点SECRET_KEYapi/.env里负责加密会话等敏感数据必须生成随机值Linux 下sed -i /^SECRET_KEY/c\\SECRET_KEY$(openssl rand -base64 42) .env一条命令搞定macOS 的sed语法略有差异需先取值再写入COOKIE_DOMAIN当前后端与前端部署在不同子域时必须设为站点顶级域名如example.com否则两边共享不了认证 Cookie表现为前端登录后接口全部 401。前端pnpm 根工作区 vinext 开发栈前端是 Next.js 应用JS 依赖统一由仓库根的工作区文件package.json、pnpm-lock.yaml、pnpm-workspace.yaml管理所以一切从仓库根执行别cd web再装依赖pnpm install cp web/.env.example web/.env.local pnpm devpnpm dev拉起的默认开发栈包含 vinext 和本地 API 代理路由归属定义在 web/dev-proxy.config.ts只有明确需要裸 Next.js 开发服务器时才用pnpm -C web dev。web/.env.local里两个关键变量NEXT_PUBLIC_API_PREFIX和NEXT_PUBLIC_PUBLIC_API_PREFIX指向你的后端 API 地址指错了前端会满屏请求失败跨子域部署时还要设NEXT_PUBLIC_COOKIE_DOMAIN。之后编辑 web/app 下任何文件页面都会自动热更新。第五步提交前跑一遍质量自查Dify 前后端各有一套固定的质量工具链PR 合入前 CI 会跑本地先跑通能省下往返时间。后端pytest、ruff 与 pyrefly测试环境依赖装好后在api目录运行测试所需的模拟系统环境变量已配在pyproject.toml的tool.pytest_env段里uv sync --group dev uv run pytest # 全量 uv run pytest tests/unit_tests/ # 仅单元测试 uv run pytest tests/integration_tests/ # 集成测试api/tests/下分三层unit_tests/、integration_tests/、test_containers_integration_tests/。代码质量方面./dev/reformat # 一键跑全部格式化与 linter uv run pyrefly check # 单独跑类型检查./dev/reformat依次做五件事lint-imports校验模块分层不越界、ruff check --fix修 lint 问题、ruff format统一格式、dotenv-linter校验前后端.env.example注释一致、本地 pyrefly 类型检查。另外 api/AGENTS.md 也提供make lint、make type-check、make test的等价入口。前端vp test 跑单元测试别碰 vitest前端测试用 Vitest React Testing Library但由于项目跑在 Vite 上vitest命令不可用必须用vpcd web vp test run --project unit三条要点标准单元测试跑在happy-dom环境browser项目只留给确实依赖真实浏览器行为的测试CSS 布局、原生焦点行为、真实指针输入不要跑裸vp test它会执行所有已注册项目包括 Browser Mode。测试什么时候该写、什么时候不用写web/docs/test.md 有完整准则核心一条测试保护的是可观测的行为契约交互结果、导航与持久化、可到达的加载/错误/空状态而不是给文件存在或覆盖率缺口打补丁。后端分层自查清单改后端代码前把 api/AGENTS.md 的架构约定当提交前自查清单过一遍传输解析/序列化留在 controllers编排逻辑放 services领域策略放core/或其领域归属模块配置统一走configs.dify_config读取存储走extensions.ext_storage.storage出站 HTTP 必须复用现有的 SSRF 安全出口core.helper.ssrf_proxySSRF 防护防止服务端被诱导请求内网地址请求/响应模型用 Pydantic v2领域异常在 controller 边界处翻译异步工作复用现有 Celery 任务归属者可重试任务必须保持副作用幂等重复投递不产生重复效果改 controller schema 或SystemFeatureModel之前先读 api/controllers/API_SCHEMA_GUIDE.md。第六步从分支到合并PR 提交前检查清单把官方 PR 流程收敛成一份可直接对照的清单相关 Issue 已存在——没有就先创建并讨论方案先 Issue 后 PR是硬规则已 Fork 仓库并为本次改动新建独立分支一个 PR 只装一个主题的改动改动影响了可观测行为或有回归风险时已补充/更新测试本地全量测试通过后端uv run pytest前端vp test run --project unit质量工具链全绿后端./dev/reformatuv run pyrefly checkPR 描述中用fixes #issue 编号关联 Issue合并后该 Issue 会自动关闭提交后等待审阅按评论迭代直到合并。记住这几条就够三类入口投三个地方平台代码进主仓库新模型/新工具进dify-plugins已有插件修复进dify-official-plugins后端 Bug 报告没有docker-compose logs日志基本不受理Issue 先行PR 用fixes #关联没关联的 PR 会被要求补环境靠dev/脚本 uv后端 pnpm 根工作区前端一键化质量自查 后端 pytest/ruff/pyrefly前端vp test改后端前先过 AGENTS.md 分层约定。卡住了怎么办两个渠道直接在对应 Issue 下追问维护者或加入 Dify 官方 Discord 社区入口见仓库根 README.md 的 Community 部分快速交流。祝你的第一个 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），仅供参考