企业官网建设流程全解析

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

Dify 是面向团队的 LLM 应用开发平台。本文覆盖 Dify 开源贡献的完整闭环：领 good first issue、按 uv 与 pnpm 工作区搭建本地开发环境、遵守 Bug 报告规范，直到提交 PR 并等合并，并整理关键的测试与调试命令。

开工前：三张"准入票"

请先阅读 LICENSE 中的许可证与 Contributor Agreement，并确认遵守社区 Code of Conduct。另外，贡献文档本身是活文档，描述落后于项目现状时，反馈修正即是一次有效贡献。

任务入口：你的 Issue 在哪领

1. 浏览带good first issue标签的开放 Issue，挑选一个入门任务；
2. 新增模型运行时或新工具，提交到独立插件仓库dify-plugins，不进主仓库；
3. 更新已有插件或修复插件 Bug，提交到官方插件仓库dify-official-plugins。

PR 描述必须关联一个已存在的 Issue，或先开 Issue 讨论再开 PR。从源码结构可以印证这条分工：主仓库 api/core/plugin/ 负责插件运行时与插件服务端的通信，模型运行时与工具的具体实现都在插件仓库里。

上游沟通：报告与请求的"最小完备集"

Bug 报告必含字段

• 清晰且具描述性的标题
• 详细的 Bug 描述，包含完整错误信息
• 可复现的步骤（steps to reproduce）
• 期望行为（expected behavior）
• 后端问题必须附日志，通过docker-compose logs获取
• 如适用，附截图或视频

缺陷优先级分级

功能请求必含字段

• 清晰且具描述性的标题
• 功能的详细描述
• 该功能的应用场景（use case）
• 其他上下文或截图

功能优先级分级

交付流水线：Fork → Merge 七步

1. Fork 仓库；
2. 起草 PR 之前，先创建 Issue 讨论你要做的改动；
3. 为新改动创建独立分支；
4. 当改动影响可观测行为或存在实质回归风险时，添加或更新测试；
5. 确保代码通过既有测试；
6. 在 PR 描述中用fixes #<issue_number>关联 Issue；
7. 等待合并。

第 4 步对应仓库明确的测试理念：测试保护的是可观测契约，即用户交互与 UI 状态、导航与持久化、可达的加载/成功/错误/空状态、可访问性语义，以及可通过公开边界复现的回归 Bug。不要仅因"文件存在""覆盖率缺口"或"TypeScript 已保证类型"而补测试。

本地开发栈：前后端一键拉起

后端（Python + uv）

自 v1.3.0 起，后端包管理器从 poetry 切换到 uv；官方推荐使用 dev/ 下的脚本，脚本相对自身位置解析路径，任意目录可执行。

./dev/setup # 拷贝 env 文件并安装依赖 # 检查 api/.env、web/.env.local、docker/middleware.env 取值 ./dev/start-docker-compose # 启动 PostgreSQL/Redis/Weaviate ./dev/start-api # 启动后端，先执行数据库迁移 ./dev/start-web # 启动前端 # 访问 http://localhost:3000 完成应用初始化 ./dev/start-worker # 启动 worker（异步与定时任务） ./dev/start-beat # 可选：启动 Celery Beat

关键环境变量：

• SECRET_KEY：必须在.env中生成随机值，Linux 下执行sed -i "/^SECRET_KEY=/c\\SECRET_KEY=$(openssl rand -base64 42)" .env
• COOKIE_DOMAIN：前后端运行在不同子域时，设为站点顶级域名（如example.com），两端须处于同一顶级域下才能共享认证 Cookie

macOS 的sed语法不同，需先取值再写入：

secret_key=$(openssl rand -base64 42) sed -i '' "/^SECRET_KEY=/c\\ SECRET_KEY=${secret_key}" .env

前端（Next.js + 根目录 pnpm workspace）

Node.js 与 pnpm 版本由根 package.json 的devEngines.runtime与packageManager字段锁定，JavaScript 依赖由根工作区文件统一管理，请从仓库根目录执行安装。

pnpm install # 根目录安装依赖 cp web/.env.example web/.env.local # 创建本地环境变量 pnpm dev # 启动 vinext 与本地 API 代理

两个易错点：

• 前端与后端不同子域部署时，设置NEXT_PUBLIC_COOKIE_DOMAIN
• 将NEXT_PUBLIC_API_PREFIX与NEXT_PUBLIC_PUBLIC_API_PREFIX指向正确的后端 API 地址

仅当明确需要裸 Next.js 开发服务器（不走 vinext）时才用pnpm -C web dev，路由归属定义在 web/dev-proxy.config.ts；UI 组件开发可用pnpm -C web storybook启动 Storybook，访问 6006 端口。

api/README.md 与 web/README.md 是排障的第一手资料，涵盖前置条件与依赖、安装步骤、配置细节与常见排障提示。

质量门禁：测试、Lint 与架构红线

后端测试与格式化

cd api uv sync --group dev # 安装测试环境依赖 uv run pytest # 全部测试 uv run pytest tests/unit_tests/ # 仅单元测试 uv run pytest tests/integration_tests/ # 集成测试 ./dev/reformat # 全部格式化器与 linter uv run ruff check --fix ./ # 修复 lint 问题 uv run ruff format ./ # 格式化代码 uv run pyrefly check # 类型检查

dev/reformat 实际串联：lint-imports（架构分层检查）→ruff check --fix→ruff format→dotenv-linter（校验api/.env.example与web/.env.example的注释一致性）→ 本地 pyrefly 类型检查。

api/tests/ 下分unit_tests/、integration_tests/、test_containers_integration_tests/三层，测试所用的模拟系统环境变量配置在pyproject.toml的tool.pytest_env段。

前端测试

cd web vp test run --project unit

项目采用 Vite+，vitest命令不可用，必须走vp命令。标准单元测试运行在happy-dom环境；Browser Mode 仅保留给依赖真实浏览器行为的测试（CSS 布局、原生焦点行为、真实指针输入等）。别用裸vp test，它会运行所有已注册项目，包括 Browser Mode。

架构分层自查

按 api/AGENTS.md 的分层约定自查：controller 管传输解析与序列化，service 管编排逻辑，core/或领域归属模块管领域策略。配置统一经configs.dify_config读取，出站 HTTP 走现有的 SSRF 安全出口core.helper.ssrf_proxy，请求与响应模型使用 Pydantic v2，异步工作复用现有 Celery 任务归属者，可重试任务必须保持副作用幂等。修改 controller schema 或SystemFeatureModel之前，请先读 api/controllers/API_SCHEMA_GUIDE.md。

卡住了：两个求助口

最直接的求助口是对应的 Issue 区，维护者会关注活跃讨论，直接在 Issue 中提问。更快的交流入口是 Dify 官方 Discord，入口见根 README.md 的 Community 部分。

收束

以 Issue 为先导，以插件仓库承接模型与工具扩展，以dev/脚本驱动 uv 与 pnpm 工作区的本地开发栈，以 ruff、pyrefly、vp test两套工具链守住质量门禁。四件事串起来，就是一次从领 Issue 到等合并的完整 Dify 开源贡献闭环。

【免费下载链接】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