企业官网建设流程全解析

如果你正在使用 Dify 构建 AI 应用，是否曾有过这样的困惑：为什么我的应用界面看起来和别人的一模一样？当我想把应用嵌入到自己的官网，或者想调整一下配色、Logo，甚至修改整个布局来匹配品牌风格时，却发现无从下手？

这恰恰是很多开发者在初步体验 Dify 后遇到的核心痛点。Dify 以其强大的工作流和知识库能力，极大地简化了 AI 应用的构建过程，但其开箱即用的 Web UI 更像是一个标准化的“演示间”。对于希望将 AI 能力深度集成到自有产品、打造独特用户体验的团队来说，这个“演示间”就显得过于简陋和同质化了。

很多人误以为 Dify 只是一个封闭的 SaaS 平台，其 UI 无法定制。实际上，这是一个巨大的误解。Dify 的核心价值在于其强大的后端引擎（工作流编排、模型调度、知识库处理），而其前端 UI 是完全开源且可高度定制的。真正的挑战不在于“能不能改”，而在于“怎么改”才能既保持 Dify 后端能力的稳定性，又实现前端的个性化。

本文将彻底拆解 Dify 应用 UI 的个性化自定义路径。我不会只告诉你“可以改”，而是会带你从原理上理解 Dify 的前后端分离架构，并给出从简单样式覆盖到深度二次开发的全套实操方案。无论你是想换个 Logo 和主题色，还是需要将 AI 对话组件无缝嵌入你的 React/Vue 项目，甚至是基于 Dify 后端构建一个全新的前端应用，你都能在本文找到清晰的步骤和可运行的代码。

1. 理解 Dify UI 定制的核心：前后端分离与开源仓库

在动手修改任何代码之前，必须建立正确的认知：Dify 的 Web 界面和其后端服务是彻底分离的。

后端（Backend）：提供所有核心 API。包括工作流的创建与运行、会话管理、知识库的检索与上传、模型推理等。这是 Dify 的“大脑”，通常通过 Docker 容器或直接部署运行。前端（Web UI）：一个独立的、基于现代前端框架（React + TypeScript）构建的单页应用（SPA）。它通过调用后端 API 来呈现界面和交互。这个“外壳”就是我们可以大做文章的地方。

Dify 官方将 Web UI 的代码完全开源在 GitHub 上。这意味着我们拥有最高权限的修改自由。整个定制化过程，本质上就是对这个前端项目进行“二次开发”。

常见的定制需求可以分为三个层次，难度逐级递增：

1. 表层定制：修改品牌标识、主题颜色、文案等。通过环境变量或简单代码替换即可实现。
2. 布局与组件定制：调整页面结构、增删部分功能模块（如侧边栏、底部信息）。需要修改 React 组件代码。
3. 深度集成与重构：将 Dify 的特定功能（如聊天窗口、知识库上传）以组件形式嵌入到自有系统中，或完全重写前端。这需要较强的全栈开发能力。

下面的路线图清晰地展示了从易到难的三种自定义路径及其关键技术点：

flowchart TD A[Dify UI 自定义需求] --> B{评估定制深度}; B -->|最简单| C[路径一: 基础品牌定制]; B -->|中等难度| D[路径二: 布局与组件修改]; B -->|最高自由度| E[路径三: 深度集成/重构]; subgraph C_Group [表层修改] C1[修改 Logo/标题] C2[调整主题色] C3[替换文案] end C --> C_Group C_Group --> F[通过环境变量<br>或直接替换资源文件实现]; subgraph D_Group [源码级修改] D1[克隆官方前端仓库] D2[修改 React 组件] D3[调整 CSS/布局] D4[构建并部署] end D --> D_Group D_Group --> G[需熟悉 React/TypeScript]; subgraph E_Group [架构级整合] E1[将 Dify 作为纯后端] E2[使用 API/SDK 调用] E3[在自有前端中嵌入功能组件] E4[或完全重写前端界面] end E --> E_Group E_Group --> H[需全栈能力<br>实现前后端解耦];

接下来，我们将沿着这三条路径，逐一深入。

2. 环境准备：获取定制化的“原材料”

无论选择哪条路径，第一步都是准备好“原材料”——Dify 的前端代码和运行环境。

2.1 获取前端源码

访问 Dify 官方 GitHub 仓库：https://github.com/langgenius/dify。注意，前端代码位于仓库的web目录下。更直接的方式是关注langgenius/dify-frontend这个仓库（如果存在），但通常主仓库的web目录就是前端项目。

最稳妥的方式是克隆整个 Dify 仓库，然后专注于web目录。

# 克隆仓库 git clone https://github.com/langgenius/dify.git cd dify # 前端项目就在 web 目录下 cd web

2.2 环境配置

Dify 前端是一个基于 Vite + React + TypeScript 的项目，需要 Node.js 环境。

1. 安装 Node.js：确保版本在 16.x 或以上（推荐 18.x LTS）。可以使用nvm管理多版本。
2. 安装依赖：进入web目录，安装项目依赖。

# 进入前端目录 cd /path/to/dify/web # 使用 npm 或 yarn 安装依赖 (推荐使用 yarn，与项目锁文件一致) npm install # 或 yarn install

3. 配置环境变量：前端需要知道后端 API 的地址。复制环境变量模板文件并修改。

# 复制环境变量示例文件 cp .env.example .env

打开.env文件，关键配置项如下：

# 后端 API 服务地址。如果你在本地运行 Dify 后端，通常是： VITE_API_PREFIX=http://localhost:5001/v1 # 如果你使用官方 Docker-Compose，且前端通过 Nginx 代理，可能是： VITE_API_PREFIX=/api # 应用名称，会显示在浏览器标签页等位置 VITE_APP_TITLE=My Dify AI # 版权信息 VITE_COPYRIGHT=My Company © 2024

重要：VITE_API_PREFIX必须与你的后端服务地址匹配，否则前端将无法连接到后端。

3. 路径一：基础品牌定制（最快见效）

这个路径适合只需要更换 Logo、应用名称、主题色等品牌元素的用户。无需深入代码逻辑。

3.1 替换 Logo 和图标

Dify 的 Logo 资源主要存放在web/public目录下。这是 Vite 项目的静态资源目录，构建时会直接复制到输出根目录。

• 浏览器标签页图标：替换web/public/favicon.ico。
• Logo 图片：主要的 Logo 文件是web/public/logo.png和web/public/logo-white.png（用于深色背景）。请用你的 Logo 文件同名覆盖即可。建议保持相似的尺寸和透明背景以获得最佳效果。

3.2 修改应用标题和文案

应用标题由环境变量VITE_APP_TITLE控制，如上节所述。修改.env文件后，重启开发服务器或重新构建即可生效。

更细粒度的文案，如登录页的标语、按钮文字、占位符等，需要修改前端代码中的国际化（i18n）文件。Dify 前端支持多语言，中文文案位于web/src/i18n/lang-cn.ts文件中。

例如，你想修改首页的欢迎标题：

1. 打开web/src/i18n/lang-cn.ts。
2. 搜索关键词，如“欢迎来到”或“Welcome to”。
3. 找到对应的键值对进行修改。修改时请注意保持 JSON 结构。

// 在 lang-cn.ts 中找到类似结构 { "app": { "name": "Dify", "description": "欢迎来到 Dify" } } // 将其修改为 { "app": { "name": "我的AI平台", "description": "欢迎使用我们的智能助手" } }

3.3 调整主题色

Dify 使用 CSS 变量和 Tailwind CSS 来管理样式。主题色主要在web/src/styles/main.css或通过 Tailwind 配置定义。

最直接的方法是覆盖 CSS 变量。你可以在web/src/styles目录下创建一个自定义的 CSS 文件（如custom.css），并在入口文件main.tsx中引入。

1. 创建web/src/styles/custom.css：

/* 覆盖主色调 */ :root { --color-primary-600: #1890ff; /* 将原来的蓝色改为 Ant Design 蓝色 */ --color-primary-500: #40a9ff; } /* 如果你想修改背景色 */ body { background-color: #fafafa; }

2. 在web/src/main.tsx中引入该文件：

import React from 'react' import ReactDOM from 'react-dom/client' import App from './App' import './styles/main.css' import './styles/custom.css' // 添加这行 // ... 其他导入

完成上述修改后，运行npm run dev即可在本地http://localhost:3000查看实时效果。

4. 路径二：布局与组件修改（需要编码）

当你需要改变页面结构，比如隐藏不需要的导航项、调整聊天窗口布局、或添加一个自定义的底部横幅时，就需要直接修改 React 组件了。

4.1 项目结构与关键组件

了解关键文件的位置是修改的前提：

• web/src/app/(commonLayout)：包含应用主布局的组件，如侧边栏、顶部导航。
• web/src/app/(main)/：包含各个主功能页面，如工作台(workspace)、聊天(chat)、工作流(workflow)。
• web/src/app/components/：可复用的通用 UI 组件。
• web/src/app/assets/：图片等资源。

4.2 实战：隐藏顶部的“探索”导航标签

假设你的应用只对内使用，不需要公开的“探索”社区功能。

1. 定位组件：顶部导航很可能在布局组件中。查看web/src/app/(commonLayout)/layout.tsx或相关的导航组件文件（如navigation.tsx）。
2. 修改代码：找到导航列表的渲染部分。它可能是一个数组navItems，通过map函数渲染。找到key为explore或标签为“探索”的项，将其从数组中移除或注释掉。

// 示例：在某个 navigation.tsx 文件中 const navItems = [ { key: 'workspace', label: '工作台', icon: <IconApps /> }, { key: 'apps', label: '我的应用', icon: <IconApp /> }, // 注释或删除下面这一行以隐藏“探索” // { key: 'explore', label: '探索', icon: <IconPublic /> }, { key: 'datasets', label: '知识库', icon: <IconDatabase /> }, ];

4.3 实战：在聊天页面侧边栏添加一个帮助按钮

这个例子展示了如何添加一个新的交互元素。

1. 定位聊天侧边栏组件：它可能位于web/src/app/(main)/chat/sidebar.tsx。
2. 修改组件：在侧边栏的合适位置（例如，会话列表下方）添加一个按钮。

// 在 sidebar.tsx 的 return 语句的 JSX 中寻找合适位置 return ( <div className="flex flex-col h-full"> {/* 原有的会话列表等 */} <div className="flex-1 overflow-auto">{/* ... */}</div> {/* 添加一个帮助按钮区域 */} <div className="p-4 border-t"> <button onClick={() => window.open('https://your-help-site.com', '_blank')} className="flex items-center justify-center w-full p-2 text-gray-600 rounded-lg hover:bg-gray-100" > <HelpCircleIcon className="w-5 h-5 mr-2" /> {/* 需要引入图标组件 */} 使用帮助 </button> </div> </div> );

3. 引入图标：如果使用了新的图标组件，记得在文件顶部导入。

4.4 构建与部署

本地修改测试无误后，需要构建生产环境代码。

# 在 web 目录下运行构建命令 npm run build # 或 yarn build

构建完成后，产物会生成在web/dist目录下。你可以：

• 将这个dist目录的内容部署到你的静态网站服务器（如 Nginx, Apache, S3）。
• 如果你使用 Docker 部署，需要修改 Dockerfile 或构建流程，将你的定制化前端代码打包进镜像。通常做法是基于官方镜像，在构建阶段复制你的web目录源码并执行yarn build。

5. 路径三：深度集成与重构（最高自由度）

这是最彻底的方案，将 Dify 完全视为一个后端 API 服务，前端完全由你自己掌控。这适合需要将 AI 能力无缝嵌入到现有产品，或对用户体验有极高定制化要求的团队。

5.1 将 Dify 作为纯后端服务

确保你的 Dify 后端服务已经部署并可通过网络访问（如https://api.your-ai.com）。你需要关注的是它的 API 文档（通常部署在/v1/apis或/docs）。

5.2 使用 API 或 SDK 进行集成

Dify 提供了相对完善的 API。你可以直接使用fetch或axios调用，也可以使用社区或官方可能提供的 SDK。

示例：在你的 Vue/React 项目中发送聊天消息

假设你的 Dify 应用 ID 是app-xxx，且已创建了一个公开访问的聊天应用。

1. 获取会话：首先创建一个会话。

// 使用 axios 示例 import axios from 'axios'; const API_BASE = 'https://api.your-ai.com/v1'; const APP_ID = 'your-app-id'; const USER_ID = 'unique-user-id-123'; // 用于标识终端用户 // 创建或获取会话 async function createConversation() { const response = await axios.post(`${API_BASE}/chat-messages`, { query: '你好', // 第一条消息 response_mode: 'streaming', // 或 'blocking' user: USER_ID, inputs: {}, }, { params: { conversation_id: '' }, // 空字符串表示创建新会话 headers: { 'Authorization': `Bearer ${API_KEY}`, // 使用 API Key 'Content-Type': 'application/json', } }); return response.data.conversation_id; }

2. 流式接收回复：对于流式响应，你需要处理 Server-Sent Events (SSE)。

async function sendMessageStreaming(conversationId, query) { const eventSource = new EventSource( `${API_BASE}/chat-messages?conversation_id=${conversationId}&query=${encodeURIComponent(query)}&user=${USER_ID}&response_mode=streaming` ); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); if (data.event === 'message' || data.event === 'agent_message') { // 处理消息内容 data.answer console.log('收到片段:', data.answer); } else if (data.event === 'message_end') { eventSource.close(); console.log('消息接收完毕'); } }; eventSource.onerror = (error) => { console.error('EventSource failed:', error); eventSource.close(); }; }

5.3 嵌入聊天窗口组件

如果你不想从头实现所有 UI 逻辑，可以提取 Dify 前端中的聊天组件 (web/src/app/components/chat/chat.tsx及相关组件) 进行复用。但这需要你理解其内部状态管理（如使用 Zustand 的 store）和样式依赖，复杂度较高。更推荐基于 API 自己实现一个简化的、风格匹配的聊天组件。

5.4 完全重写前端

这是自由度最高的方式。你可以使用任何前端框架（Next.js, Nuxt.js, 甚至静态站点），设计完全符合你品牌和交互规范的界面，只通过 API 与 Dify 后端通信。这相当于你只使用了 Dify 的“引擎”，自己制造了“车身和内饰”。

6. 构建、部署与版本管理

6.1 构建优化

在web目录下，构建命令会生成优化后的静态文件。

# 生产环境构建 yarn build # 或指定模式 yarn build:prod

构建后，务必检查dist目录下的index.html和资源文件是否正常。

6.2 部署方式

• 静态服务器：将dist目录部署到 Nginx、Apache、云存储（S3+CloudFront）等。

  # Nginx 示例配置 server { listen 80; server_name ai.yourdomain.com; root /path/to/dify-web/dist; index index.html; location / { try_files $uri $uri/ /index.html; # 支持前端路由 } # 代理后端 API 请求到 Dify 后端 location /api { proxy_pass http://dify-backend:5001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

• Docker 部署：创建自定义的 Dockerfile，将你的定制化前端打包。

  # 使用多阶段构建 FROM node:18-alpine AS builder WORKDIR /app COPY web/package.json web/yarn.lock ./ RUN yarn install --frozen-lockfile COPY web/ . RUN yarn build FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80

6.3 版本管理与升级

定制化最大的挑战是与上游官方版本的同步。

1. Fork 仓库：强烈建议 Fork 官方的langgenius/dify仓库到你的 GitHub 账户，然后在你的 Fork 上进行定制开发。这样你可以比较方便地查看官方更新。
2. 分支策略：在你的仓库中，为你的定制版本创建一个稳定的分支（如custom-v1）。当官方发布新版本时，可以尝试将官方分支合并到你的定制分支，解决代码冲突。
3. 关注变更：重点注意你修改过的文件（如lang-cn.ts,sidebar.tsx,main.css）在官方更新中是否也被修改了。使用 Git 的 diff 和 merge 工具仔细处理。

7. 常见问题与排查思路

在 UI 定制过程中，你可能会遇到以下问题：

8. 最佳实践与工程建议

1. 渐进式定制：不要一开始就试图大改。从修改环境变量和 Logo 开始，然后是文案和颜色，最后再动组件和布局。每一步都验证效果。
2. 善用 Git：每次进行一个明确的修改就提交一次。写清晰的提交信息。这在你需要合并官方更新或回退时至关重要。
3. 维护一个变更清单：建立一个文档（如CUSTOMIZATION.md），记录你修改了哪些文件、为什么修改、以及如何与官方版本同步。这对于团队协作和未来维护是无价之宝。
4. 隔离自定义样式：尽量将自定义的 CSS 写在独立的文件（如custom.css）中，而不是直接修改原有的main.css。这样在升级时更容易对比和合并。
5. 关注 API 稳定性：如果你选择深度集成路径，要意识到 Dify 后端的 API 可能还在迭代中。关注官方更新日志，并为你的前端 API 调用层做好抽象和错误处理，以应对可能的变更。
6. 性能与安全：
   • 构建时进行代码压缩和优化。
   • 如果你公开了前端，确保后端的 API Key 或敏感信息不会在前端代码中泄露。所有密钥都应通过后端服务中转。
   • 为你的自定义前端域名配置 HTTPS。

Dify 的 UI 定制，从本质上讲，是一个标准的现代前端工程问题。它考验的不是你对某个神秘配置的掌握，而是你对前后端分离架构、React 技术栈、构建部署流程以及版本管理的基本功。理解了这个本质，无论是简单的换肤，还是复杂的重写，你都能找到清晰、可控的实施路径。最关键的起点，就是克隆下代码，运行起来，然后从修改一个环境变量开始。