飞书插件前端开发流程一、开发环境准备为确保飞书插件前端开发的顺利进行，请务必配置以下环境。项目要求/说明开

一、开发环境准备

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


项目	要求/说明
开发框架	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：本地开发与调试

核心操作流程：

拉取代码：在 飞书开放平台后台 中，进入对应应用详情，点击 “复制初始化命令” 。
开启调试：在 飞书开放平台后台 中，进入对应应用详情，开启 “本地调试” 模式。
启动项目：在本地项目根目录下执行命令 lpm start，启动本地开发服务器。
配置插件：以控件为例，首先要在空间配置里的页面布局添加插件。

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 使用限制

无法使用 axios.create 新建实例，平台对其做了限制
使用 axios 调用接口时，接口 URL 必须为绝对路径（含域名），否则将调用失败
如调用任何 *.feishu.cn 子域名下的接口都将被限制，会调用失败

请求飞书项目 OpenAPI

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

六、相关文档地址

飞书开发文档：project.feishu.cn/b/helpcente…
React中文文档：react-js.cn/learn
Semi-Ui文档：semi.design/zh-CN/start…

飞书插件前端开发流程

一、 开发环境准备

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