1. 项目概述为什么从零开始一个飞书小程序Demo如果你是一名开发者最近肯定没少听到“飞书”、“小程序”、“Agent”这些词。飞书作为一款集成了IM、日历、文档、视频会议等功能的协同办公平台其开放平台的能力正在被越来越多的企业和开发者关注。尤其是飞书小程序它允许你将定制化的应用直接嵌入到飞书的工作台、群聊甚至单聊中实现业务与沟通的无缝融合。相比于微信小程序主要面向C端消费场景飞书小程序更侧重于提升B端企业内部的工作效率和流程自动化。那么当我们要学习一项新技术时最高效的方式是什么没错就是动手做一个Demo。这个“飞书小程序Demo”项目目标就是通过一个完整的、可运行的实例带你穿透官方文档的迷雾直击开发的核心流程、关键配置和那些文档里不会写的“坑”。这不仅仅是跟着教程点下一步而是理解每一个操作背后的意图掌握从环境搭建、代码编写、调试到最终上线的完整闭环。无论你是前端开发者想拓展技术栈还是后端工程师希望了解如何为飞书生态提供能力这个Demo都将是一个绝佳的起点。2. 飞书小程序开发环境全链路配置开发飞书小程序你不需要安装一个特殊的“飞书开发者工具”这与微信小程序不同。飞书小程序的开发更接近于现代前端开发流程核心是在浏览器中进行的。但这并不意味着环境配置可以掉以轻心一个稳定、高效的本地环境是后续所有工作的基石。2.1 核心工具链选型与安装飞书官方推荐并主要支持基于React技术栈的开发。因此我们的工具链将围绕 React 生态来构建。Node.js 与 npm/yarn/pnpm这是所有现代前端项目的基石。你需要安装 Node.js建议选择最新的 LTS 版本如 18.x 或 20.x。安装完成后node -v和npm -v命令能正常输出版本号即表示成功。我个人更推荐使用pnpm作为包管理器它在速度和磁盘空间利用上更有优势。你可以通过npm install -g pnpm全局安装它。代码编辑器Visual Studio Code (VS Code) 是绝大多数前端开发者的首选。你需要为其安装一些必要的插件来提升开发体验ES7 React/Redux/React-Native snippets提供React组件、生命周期等代码片段极大提升编码速度。Prettier - Code formatter代码格式化工具保证团队代码风格统一。建议配置保存时自动格式化。飞书小程序开发者工具插件在VS Code扩展商店搜索“Lark Mini Program”或“飞书小程序”安装官方插件。这个插件至关重要它提供了项目创建、真机预览、上传等核心功能的图形化界面和命令。浏览器开发者工具飞书小程序的调试主要在浏览器中进行。Chrome 或 Edge 的开发者工具是你最好的朋友。请确保你熟悉其Elements元素检查、Console控制台、Sources源代码调试、Network网络请求等面板的基本用法。注意避免使用某些可能修改网络代理的浏览器插件或系统设置这可能会导致与飞书服务器通信异常出现无法登录开发者后台或预览失败的问题。保持一个干净的网络环境是顺利开发的第一步。2.2 飞书开发者后台的“关键配置”详解环境搭好了我们得有个“地盘”来创建和管理我们的小程序。这个地盘就是飞书开发者后台。很多新手在这里卡住不是因为步骤复杂而是不理解每个配置项的意义。注册与创建应用访问飞书开放平台官网用你的飞书账号登录。在“开发者后台”点击“创建企业自建应用”。给应用起个名字比如“我的第一个Demo”。这里创建的“应用”是一个容器小程序是它的能力之一。获取关键凭证App ID 与 App Secret创建成功后在应用的“凭证与基础信息”页面你会看到App ID和App Secret。请像保护密码一样保护App Secret尤其不要提交到代码仓库。这两个凭证是你的应用在飞书系统中的唯一身份证后续所有服务器API调用如获取用户信息、发送消息都依赖它们。配置安全域名重要这是最容易出错的一步。在“安全设置”页面你需要设置“Web 页面”的“可信域名”。这里填的是你开发服务器的访问地址。如果你使用官方脚手架本地开发服务器通常是http://localhost:3000。但注意飞书要求必须是HTTPS域名localhost除外。所以如果你需要手机真机预览手机和电脑不在同一局域网或者想部署一个测试环境你需要一个HTTPS域名。开发阶段我们通常先用localhost并配合电脑和手机在同一WiFi下来预览。启用小程序能力在应用管理的“功能”板块找到“小程序”并启用它。启用后你需要在这里设置小程序的“主页地址”这个地址就是你的开发服务器启动后那个能访问到小程序首页的URL例如http://localhost:3000。版本管理与发布飞书小程序有明确的版本概念开发版本开发者上传、体验版本可供指定成员测试、审核版本提交官方审核、线上版本全公司可用。我们做Demo主要与“开发版本”打交道。通过VS Code插件或命令行工具将代码上传后会在后台生成一个开发版本你可以扫码在飞书App中预览。3. 从零构建你的第一个Demo页面理论准备就绪现在让我们动手写代码。飞书官方提供了脚手架工具可以快速生成项目结构。3.1 项目初始化与结构解析打开终端在你选定的目录下运行以下命令来创建项目# 使用 npm npx larksuite-open/webpack-cli create my-first-demo # 或使用 pnpm pnpm create larksuite-open/webpack my-first-demo创建过程中命令行会交互式地询问一些配置如项目名称、描述等通常一路回车用默认值即可。创建完成后用VS Code打开项目文件夹。你会看到类似如下的结构my-first-demo/ ├── node_modules/ # 项目依赖包 ├── public/ # 静态资源目录 ├── src/ # 源代码目录 │ ├── app.js # 小程序应用入口配置全局样式、生命周期 │ ├── app.css # 全局样式 │ ├── index.js # 小程序首页入口 │ ├── index.css # 首页样式 │ └── pages/ # 其他页面目录 ├── .env # 环境变量配置 ├── package.json # 项目配置和依赖声明 └── webpack.config.js # 构建配置这个结构非常清晰。src/app.js是小程序的“大脑”负责全局逻辑。src/index.js是默认启动的首页。飞书小程序使用JSX语法编写组件对于React开发者来说几乎零门槛。3.2 核心组件与API初体验让我们修改src/index.js创建一个简单的交互页面。// src/index.js import React, { useState } from react; import { Button, View, Text } from larksuite-open/mini-ssr; // 引入飞书小程序UI组件库 import * as lark from larksuite-open/js-sdk; // 引入飞书JS SDK import ./index.css; export default function Index() { // 使用React的useState Hook管理状态 const [count, setCount] useState(0); const [userInfo, setUserInfo] useState(null); // 一个简单的计数器函数 const handleIncrement () { setCount(count 1); }; // 调用飞书API获取用户信息 const handleGetUserInfo async () { try { // 调用SDK的getUserInfo方法 const res await lark.getUserInfo(); if (res res.data) { setUserInfo(res.data); console.log(用户信息获取成功:, res.data); } } catch (error) { console.error(获取用户信息失败:, error); // 在实际项目中这里需要更友好的错误提示 } }; return ( View classNamecontainer Text classNametitle欢迎来到飞书小程序Demo/Text View classNamesection Text计数器: {count}/Text Button typeprimary onClick{handleIncrement} 点我加一 /Button /View View classNamesection Button onClick{handleGetUserInfo}获取我的飞书信息/Button {userInfo ? ( View classNameuser-info Text姓名: {userInfo.name}/Text Text部门: {userInfo.department}/Text {/* 注意avatar属性可能需要特殊处理这里只是示例 */} /View ) : ( Text未获取用户信息/Text )} /View /View ); }同时我们更新一下src/index.css添加一些基本样式/* src/index.css */ .container { padding: 24px; display: flex; flex-direction: column; align-items: center; min-height: 100vh; background-color: #f5f5f5; } .title { font-size: 20px; font-weight: bold; margin-bottom: 32px; color: #1f2329; } .section { background: white; border-radius: 8px; padding: 16px; margin-bottom: 16px; width: 100%; max-width: 400px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); } .user-info { margin-top: 12px; padding: 12px; background-color: #f0f6ff; border-radius: 4px; border-left: 4px solid #3370ff; }代码解析与注意事项组件引入larksuite-open/mini-ssr是飞书官方提供的适配小程序的React组件库它包含了View,Text,Button,Image等基础组件其属性与用法和React Native或常规Web组件类似但有些许差异需查阅官方组件文档。SDK引入larksuite-open/js-sdk是飞书JavaScript SDK它封装了与飞书客户端交互的能力如lark.getUserInfo(),lark.navigateTo(),lark.request()等。所有飞书特有的能力都通过这个SDK调用。异步操作调用飞书API通常是异步的返回Promise务必使用async/await或.then/.catch进行正确处理并在界面上给出加载或错误状态反馈。样式作用域飞书小程序的样式基本遵循CSS标准但注意样式是全局作用域的。虽然我们在index.css中写样式但如果其他页面有同名的类选择器可能会产生冲突。建议使用CSS Modules或更严格的命名约定如BEM来规避。3.3 开发服务器启动与实时预览在项目根目录下运行npm start或pnpm start开发服务器就会启动通常在http://localhost:3000。此时用浏览器打开这个地址你应该能看到一个简单的页面有标题、计数按钮和获取用户信息的按钮。但是在浏览器里点击“获取我的飞书信息”按钮会失败。因为lark.getUserInfo()这个API必须在飞书客户端环境内才能正常调用它需要飞书App提供用户上下文。在纯浏览器环境SDK无法工作。那么如何真机调试呢确保代码已通过VS Code的飞书插件或命令行npm run upload:lark上传到飞书开发者后台生成一个开发版本。在飞书开发者后台找到该开发版本会提供一个二维码。用手机飞书App登录与开发者后台相同的企业扫描这个二维码。此时你将在手机飞书内打开你的小程序。点击“获取我的飞书信息”按钮会弹出授权窗口同意后你就能在界面上看到自己的姓名和部门信息了。这个“浏览器开发 - 上传 - 手机飞书预览”的循环就是最基本的开发调试流程。4. 深入核心页面路由、数据流与生命周期一个Demo不能只有一个页面。让我们深入一点看看如何管理多页面、组件间通信以及应用的生命周期。4.1 多页面路由与传参飞书小程序的路由系统是栈式管理与React Router或Vue Router概念相似但API是飞书SDK提供的。创建新页面在src/pages/目录下新建一个文件夹例如detail在里面创建index.js和index.css文件。这即是一个新页面。配置路由可选在较新的脚手架中pages/目录下的文件夹会自动被注册为路由。你可以在app.js中查看或配置页面列表。页面跳转与传参从首页跳转到详情页// 在 src/index.js 中 import * as lark from larksuite-open/js-sdk; const handleNavigateToDetail () { lark.navigateTo({ url: /pages/detail/index?itemId${count}, // 传递参数 }); }; // 在返回的JSX中增加一个按钮 Button onClick{handleNavigateToDetail}查看详情/Button在详情页接收参数// src/pages/detail/index.js import React from react; import { View, Text } from larksuite-open/mini-ssr; import * as lark from larksuite-open/js-sdk; export default function DetailPage() { // 飞书小程序中页面参数通过 lark.getLaunchOptionsSync() 获取 const launchOptions lark.getLaunchOptionsSync(); const { query } launchOptions; // query 包含URL参数 const itemId query.itemId || 无; return ( View Text这是详情页/Text Text接收到的参数 itemId 是: {itemId}/Text /View ); }返回上一页在详情页可以通过lark.navigateBack()返回。实操心得飞书小程序的页面路由参数传递在开发阶段浏览器和真机阶段飞书客户端的行为可能略有差异。在真机中参数传递非常稳定。但在浏览器开发时由于没有飞书客户端的上下文lark.getLaunchOptionsSync()可能无法获取到通过navigateTo传递的参数。这是正常的不必纠结以真机调试为准。对于复杂的数据传递建议使用全局状态管理如Context、Redux或本地存储。4.2 状态管理从useState到Context对于简单的Demo使用React自带的useState和useEffect管理组件内部状态已经足够。但当状态需要在多个页面或多个相距甚远的组件间共享时就需要更强大的工具。飞书小程序本质上是一个React应用因此所有React生态的状态管理方案理论上都可以使用。对于中小型项目React Context API 是一个简单而有效的选择。创建Context// src/contexts/UserContext.js import React, { createContext, useState, useContext } from react; const UserContext createContext(null); export const UserProvider ({ children }) { const [currentUser, setCurrentUser] useState(null); const [isLoading, setIsLoading] useState(false); // 可以在这里封装一个获取用户信息的函数 const fetchUserInfo async () { setIsLoading(true); try { const res await lark.getUserInfo(); setCurrentUser(res.data); } catch (error) { console.error(Fetch user failed:, error); } finally { setIsLoading(false); } }; return ( UserContext.Provider value{{ currentUser, isLoading, fetchUserInfo }} {children} /UserContext.Provider ); }; // 自定义Hook方便使用 export const useUser () { const context useContext(UserContext); if (!context) { throw new Error(useUser must be used within a UserProvider); } return context; };在应用顶层提供Context// src/app.js import React from react; import { UserProvider } from ./contexts/UserContext; import ./app.css; function App({ children }) { return UserProvider{children}/UserProvider; } export default App;在任何子组件中使用// 在 src/index.js 或任何页面组件中 import { useUser } from ../contexts/UserContext; export default function SomeComponent() { const { currentUser, isLoading, fetchUserInfo } useUser(); // ... 直接使用 currentUser 等信息 }这样用户信息在整个小程序中都是共享的无需层层传递props。4.3 应用与页面生命周期理解生命周期有助于你在正确的时机执行初始化、清理或数据获取操作。应用生命周期在src/app.js中定义。// src/app.js import React from react; import ./app.css; function App({ children }) { // 应用启动时执行适合做全局初始化 React.useEffect(() { console.log(小程序应用启动); // 例如初始化统计SDK、加载全局配置 return () { // 应用销毁时执行在小程序中很少触发 console.log(小程序应用销毁); }; }, []); return {children}/; } export default App;页面生命周期飞书小程序页面组件就是React函数组件因此其生命周期即React组件的生命周期useEffectHook。// 在页面组件中如 src/index.js import React, { useEffect } from react; export default function Index() { // 模拟 componentDidMount页面加载时执行一次 useEffect(() { console.log(首页加载); fetchInitialData(); // 返回的函数模拟 componentWillUnmount页面销毁时执行 return () { console.log(首页卸载); clearTimers(); }; }, []); // 空依赖数组 // 模拟 componentDidUpdate当某个状态变化时执行 const [someState, setSomeState] useState(); useEffect(() { if (someState) { console.log(someState 发生了变化:, someState); doSomethingWithState(someState); } }, [someState]); // 依赖 someState return ( ... ); }关键点飞书小程序中当从一个页面navigateTo到另一个页面时原页面默认不会被卸载而是被压入页面栈。只有调用navigateBack或redirectTo关闭当前页打开新页时页面才会卸载。这会影响useEffect清理函数的执行时机。5. 与后端交互调用API与处理网络请求一个完整的小程序不可能只有前端界面。它需要从服务器获取数据、提交表单。飞书小程序提供了lark.requestAPI 用于发起网络请求其用法类似于fetch或axios。5.1 使用lark.request调用接口假设我们有一个后端API用于获取待办事项列表。// src/services/todoApi.js import * as lark from larksuite-open/js-sdk; const API_BASE https://your-api-server.com; // 替换为你的后端地址 export const todoApi { async getTodoList() { try { const response await lark.request({ url: ${API_BASE}/api/todos, method: GET, headers: { Content-Type: application/json, // 通常这里需要携带认证Token可以从 lark.getSession() 获取 }, }); // lark.request 返回的数据结构通常为 { code, msg, data } if (response.code 0) { return response.data; // 成功返回业务数据 } else { throw new Error(response.msg || 请求失败); } } catch (error) { console.error(获取待办列表失败:, error); throw error; // 将错误抛给调用方处理 } }, async createTodo(title) { return lark.request({ url: ${API_BASE}/api/todos, method: POST, headers: { Content-Type: application/json }, data: { title }, // POST请求体数据 }); }, };在页面组件中调用import React, { useState, useEffect } from react; import { View, Text, Button } from larksuite-open/mini-ssr; import { todoApi } from ../services/todoApi; export default function TodoPage() { const [todos, setTodos] useState([]); const [loading, setLoading] useState(false); const [error, setError] useState(null); const loadTodos async () { setLoading(true); setError(null); try { const list await todoApi.getTodoList(); setTodos(list); } catch (err) { setError(err.message); } finally { setLoading(false); } }; useEffect(() { loadTodos(); }, []); if (loading) return Text加载中.../Text; if (error) return Text错误: {error}/Text; return ( View Button onClick{loadTodos}刷新列表/Button {todos.map(todo ( View key{todo.id} Text{todo.title}/Text /View ))} /View ); }5.2 处理认证与安全调用自有后端API时最大的问题是身份认证。如何让后端知道这个请求来自飞书内的某个授权用户获取用户身份凭证在小程序前端调用lark.getSession()可以获取到一个临时凭证code。const session await lark.getSession(); // 返回 { code }后端用code换用户信息前端将这个code作为请求头或参数发送给你的后端服务器。你的后端服务器再拿着这个code加上你的飞书应用的App ID和App Secret调用飞书服务端的接口/open-apis/auth/v3/app_access_token和/open-apis/authen/v1/oidc/user_info即可换取到该用户的真实身份信息如user_id,union_id等。后端颁发自有Token验证用户身份后你的后端可以生成一个自定义的JWT Token或Session ID返回给前端。前端后续的请求都携带这个Token后端据此识别用户。这是一个标准且安全的OAuth2.0流程。绝对不要将App Secret硬编码在小程序前端代码中它必须保存在你的后端服务器上。重要安全提示所有涉及敏感逻辑如数据库操作、支付、核心业务规则和存储敏感信息如App Secret、数据库密码的代码都必须放在后端服务器上。小程序前端只负责展示和收集数据通过API与后端通信。前端代码是可被用户查看和调试的没有任何秘密可言。5.3 错误处理与用户体验优化网络请求充满不确定性良好的错误处理至关重要。统一拦截器可以封装一个自定义的request函数在其中统一添加loading状态管理、错误Toast提示、请求重试、日志记录等逻辑。用户反馈在发起请求和收到响应时使用飞小程序的lark.showToast()或lark.showLoading()API给用户即时反馈。const handleSubmit async () { lark.showLoading({ title: 提交中... }); try { await api.submitForm(data); lark.showToast({ title: 提交成功, icon: success }); } catch (error) { lark.showToast({ title: 提交失败: ${error.message}, icon: none }); } finally { lark.hideLoading(); } };超时与重试lark.request可以配置timeout。对于非幂等的POST请求要谨慎重试对于GET请求可以加入简单的重试机制提升体验。6. 调试、上传与发布全流程实录开发完成后我们需要让Demo跑起来并分享给其他人测试。6.1 真机调试与问题排查浏览器开发是高效的但真机环境才是最终战场。真机调试的核心是console.log和远程调试。Console日志在代码中大量使用console.log、console.warn、console.error。在手机飞书内打开小程序后这些日志会输出到哪里如果你在Windows/Mac上使用飞书桌面版并扫码预览了同一小程序日志会输出到桌面版飞书的开发者工具控制台需在设置中开启开发者模式。更通用的方法是在手机飞书内摇一摇手机会弹出调试菜单选择“打开调试”。然后再次摇一摇选择“打开调试器”。此时小程序的Console日志会输出到一个可查看的Web面板通常需要一个内网IP地址访问。这是定位真机问题最关键的步骤。常见真机问题白屏首先检查手机网络是否正常。其次查看Console是否有JavaScript报错通常是语法错误或未定义的变量。再次检查安全域名是否配置正确开发版允许localhost体验版和上线版必须HTTPS域名。API调用失败如getUserInfo检查是否在飞书客户端内运行检查应用是否已发布“开发版本”并确保手机飞书登录的账号有该应用的试用权限在开发者后台“成员与权限”中添加。样式错乱真机浏览器内核与桌面Chrome可能有差异。多使用Flex布局避免使用太新的CSS特性。注意小程序页面根容器的高度默认是100vh但顶部可能有导航栏可使用lark.getSystemInfo()获取窗口高度进行动态计算。6.2 代码上传与版本管理当你完成一个阶段的开发后需要将代码上传到飞书后台。通过VS Code插件上传安装飞书小程序插件后侧边栏会出现飞书图标。登录你的飞书开发者账号选择对应的应用点击“上传”插件会自动打包项目并上传生成一个新的“开发版本”。通过命令行上传在项目根目录运行npm run upload:lark。这需要你在.env文件中配置好LARK_APP_ID和LARK_APP_SECRET注意保密。版本说明每次上传都会覆盖之前的“开发版本”。在开发者后台你可以看到每次上传的版本号基于package.json的version字段和上传时间。你可以将某个开发版本设置为“体验版本”供测试团队扫码体验。6.3 发布流程与审核须知从“开发版本”到全公司可用需要经过“体验版” - “提交审核” - “发布上线”流程。设置体验版在开发者后台将某个开发版本设置为体验版。你可以指定企业内的部分成员需要他们的飞书用户ID有权限体验该版本。这是进行内部测试的关键环节。提交审核当体验版测试无误后可以提交给飞书官方审核。审核主要关注内容合规性、功能完整性、用户体验等。对于Demo类应用如果仅用于个人学习或内部极小范围测试可以不提交审核一直使用体验版即可。只有需要上架到飞书应用市场或全公司强制使用时才必须审核。发布上线审核通过后你可以将该版本发布为线上版本。线上版本对所有已安装该应用的企业成员可见。避坑指南权限配置很多API如读取通讯录、发送消息需要申请相应的权限。在开发者后台“权限管理”中申请并等待管理员审核通过。没有权限对应的API调用会失败。数据安全审核时会对数据收集、存储、使用是否符合隐私政策进行审查。确保你的应用有清晰的隐私声明。性能避免首页加载过慢图片资源需压缩减少不必要的全局数据请求。7. 从Demo到实战扩展思路与性能优化完成基础Demo后你可以以此为骨架添加更多功能探索飞书小程序的深度能力。7.1 功能扩展方向接入飞书开放API飞书开放平台提供了极其丰富的服务端API你可以让你的小程序与飞书深度集成。消息卡片创建精美的交互式消息卡片发送到群聊或单人用户点击卡片可跳转到你的小程序特定页面。这对于通知、审批、任务提醒场景非常有用。机器人创建群机器人用户机器人并发送关键词触发你的后端服务并返回消息或卡片。可以实现智能问答、数据查询、流程触发等功能。日历与会议为用户创建日历事件、预约会议实现日程管理功能。云文档读取或写入飞书文档、表格的内容实现数据同步与报表生成。状态管理升级当应用复杂后可以考虑引入Zustand或Redux Toolkit这类更专业的状态管理库它们能更好地处理异步状态和复杂状态逻辑。UI组件库除了官方的基础组件可以探索社区或自行封装更丰富的业务组件如表单组件、数据表格、图表等以提升开发效率和一致性。7.2 性能优化要点代码分包随着项目增大初始加载的代码包也会变大。飞书小程序支持分包加载。你可以在app.json或类似配置文件中配置subpackages将某些独立功能的页面放到子包中用户进入对应页面时才加载显著提升首屏速度。图片等静态资源优化压缩使用工具对图片进行压缩如TinyPNG。CDN将图片、字体等静态资源部署到CDN减轻服务器压力加快加载速度。懒加载对于长列表中的图片使用飞书Image组件的lazy-load属性。数据缓存对于不常变化的数据如城市列表、配置信息可以使用lark.setStorage和lark.getStorage进行本地缓存减少网络请求。减少不必要的setData/重渲染在React中即避免在渲染函数中进行高开销计算使用useMemo和useCallback缓存计算结果和函数精确设置useEffect的依赖数组防止不必要的副作用执行。7.3 监控与运维对于正式上线的应用监控必不可少。错误监控在前端代码中集成Sentry等错误监控SDK自动捕获并上报JavaScript异常和API请求失败帮助你快速定位线上问题。性能监控关注小程序的启动时间、页面渲染时间、API响应时间等关键指标。飞书开发者后台的“数据统计”板块会提供一些基础数据。日志建立规范的日志记录机制在关键业务节点和异常处打印日志便于问题回溯。开发飞书小程序Demo的过程是一个典型的现代前端应用开发流程的缩影只不过运行环境从纯浏览器变成了飞书容器。它要求你不仅熟悉React还要理解飞书生态的特定API、安全规范和部署流程。这个Demo就像一把钥匙帮你打开了飞书应用开发的大门。门后的世界是自动化流程、是智能机器人、是深度集成的业务系统等待着你去探索和构建。