飞书插件前端开发流程

一、 开发环境准备

为确保飞书插件前端开发的顺利进行，请务必配置以下环境。

|----------------|----------------|
| 项目 | 要求/说明 |
| 开发框架 | React 18 及以上版本 |
| Node.js 版本 | 16 及以上版本 |
| 包管理工具 | npm 或 yarn |

二、 飞书开发工具 CLI 安装与配置

飞书官方提供了命令行工具 @lark-project/cli（简称 **lpm**）来管理插件生命周期。

1. 全局安装

打开命令行工具，执行以下安装命令：

npm i -g @lark-project/cli

2. 验证安装

安装完成后，通过以下命令检查版本，确认安装成功：

lpm --version

3. 常用命令列表

下表列出了开发中最常用的命令及其功能：

|-------------------|-----------------|
| 命令 | 功能说明 |
| lpm update | 同步并更新项目配置信息 |
| lpm start | 在本地启动开发服务器，用于调试 |
| lpm release | 将代码打包并上传至飞书开放平台 |

三、 标准开发流程

步骤 1：创建插件

在飞书开放平台上创建一个新的应用，获取 Plugin ID 和 Plugin Secret等关键信息，并初始化项目。

步骤 2：添加构成

根据需求在开放平台配置的插件功能里添加构成，例如：

• 控件

• 导航

• 详情页

• 配置

步骤 3：本地开发与调试

核心操作流程：

1. 拉取代码 ：在 飞书开放平台后台 中，进入对应应用详情，点击 "复制初始化命令" 。

2. 开启调试 ：在 飞书开放平台后台 中，进入对应应用详情，开启 "本地调试" 模式。

3. 启动项目 ：在本地项目根目录下执行命令 lpm start，启动本地开发服务器。

4. 配置插件：以控件为例，首先要在空间配置里的页面布局添加插件。

5.实时调试：在飞书客户端（桌面版或移动版）中访问应用，代码改动将实时热更新。

步骤 4：测试插件

在本地调试模式下，对插件的各项功能进行全面测试，确保在飞书客户端内交互正常、数据正确。

步骤 5：发布插件

1.使用 lpm release 命令上传最终代码包，会有一个版本号提示。

2.发布的时候要选择对应的版本。

3.更新你的插件，在对用的空间中，点击更新。

4.注意事项，有时可能配置完页面未更新，需要手动去更新页面。

四、UI库

飞书项目是基于Semi Design 设计系统搭建的。Semi Design 由字节跳动抖音前端与 UED 团队设计、开发并维护的企业级别设计系统，遵循全面、易用、优质的设计原则，帮助设计师与开发者打造高质量产品。

1、安装 Semi

# 使用 npm
npm i @douyinfe/semi-ui

# 使用 yarn
yarn add @douyinfe/semi-ui

# 使用 pnpm
pnpm add @douyinfe/semi-ui

2、使用组件

在 Webpack、Rspack、create-react-app 或 Vite 项目中使用时，无需进行任何编译项配置，直接使用即可。构建时所有相关资源均会按需打包

import React, { Component } from 'react';
// 如果为 React v19，需要从 @douyinfe/semi-ui-19 中导出组件
import { Button, Toast } from '@douyinfe/semi-ui';

const SemiApp = () => {
    return (
        <Button onClick={() => Toast.warning({ content: 'welcome' })}>Hello Semi</Button>
    );
};

五、接口请求

在插件内可以通过 Axios API 发起网络请求调用您的 API 或者从服务器请求资源。Axios API 的使用方式和 开源库 Axios → 是相似的。

发起请求

// src/api/index.ts 
import axios from 'axios'; 
 
export function getContentFromHTTPBin() { 
    return axios.get('https://httpbin.org/get?success=true'); 
} 

如果想对所有请求的 Request 和 Response 做拦截处理，您可以给 axios 增加拦截器

import axios from 'axios'; 
 
// Add a request interceptor 
axios.interceptors.request.use( 
  function (config) { 
    // Do something before request is sent 
    return config; 
  }, 
  function (error) { 
    // Do something with request error 
    return Promise.reject(error); 
  } 
); 
 
// Add a response interceptor 
axios.interceptors.response.use( 
  function (response) { 
    // Any status code that lie within the range of 2xx cause this function to trigger 
    // Do something with response data 
    return response; 
  }, 
  function (error) { 
    // Any status codes that falls outside the range of 2xx cause this function to trigger 
    // Do something with response error 
    return Promise.reject(error); 
  } 
 ); 

跨域调用

插件运行在浏览器环境里，所以浏览器的 Cross-Origin Resource Sharing → 策略是适用的。发起网络请求的 origin 可能是 project.feishu.com 也可能是在 origin 为 null 的 iframe 里发起（这与插件沙盒机制有关），因此我们建议您将相关 API 响应头配置成 Access-Control-Allow-Origin: *，允许来自任何源的请求。

请求 HTTP API

由于飞书项目是 HTTPs 站点，因此您无法在飞书项目里发起 HTTP 请求，这会被浏览器的 MixedContent → 策略所限制。因此您需要将您请求的 API 都升级为 HTTPs。

Axios 使用限制

1. 无法使用 axios.create 新建实例，平台对其做了限制

2. 使用 axios 调用接口时，接口 URL 必须为绝对路径（含域名），否则将调用失败

3. 如调用任何 *.feishu.cn 子域名下的接口都将被限制，会调用失败

请求飞书项目 OpenAPI

您无法在插件前端直接调用飞书项目的 OpenAPI，因为这是不安全的。您需要通过插件服务器来调用 OpenAPI。

六、 相关文档地址

1. 飞书开发文档：https://project.feishu.cn/b/helpcenter/1p8d7djs/nh4exbsn

2. React中文文档：https://react-js.cn/learn

3. Semi-Ui文档：https://semi.design/zh-CN/start/getting-started

---