Dify 开源贡献完整指南：从领 Issue 到 PR 合并-编程实验室

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 Request（PR，即代码合并请求）。跟着做完，你能独立完成从领一个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 开出来。

第三步：写出能被受理的 Issue

Issue 写得含糊，是最常见的"石沉大海"原因。下面两种类型各有硬性要素，照着清单写就不会被要求补料。

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_KEY（api/.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 dev

pnpm 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命令不可用，必须用vp：

cd 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_proxy（SSRF 防护，防止服务端被诱导请求内网地址）；
请求/响应模型用 Pydantic v2，领域异常在 controller 边界处翻译；
异步工作复用现有 Celery 任务归属者，可重试任务必须保持副作用幂等（重复投递不产生重复效果）；
改 controller schema 或SystemFeatureModel之前，先读 api/controllers/API_SCHEMA_GUIDE.md。