飞书应用开发指南：从零搭建H5应用

需要：公网域名/ip，需要对外开放

目前演示只演示一个静态页面，这个静态页面是托管在别的网站上生成的在线访问地址（不稳定，需要多次刷新才能打开）：

0ad91030-077a-451e-80b1-f692b36e6d36.wangye.domolo.cn/p/7zmzexemw…

📌 一、概述

本文档将手把手教你如何搭建一个飞书H5应用，包括：

• ✅ 创建飞书企业自建应用

• ✅ 配置应用权限与安全设置

• ✅ 开发H5页面并接入飞书JSAPI

• ✅ 在飞书客户端内调试与发布

适用场景：企业内部工具、业务系统移动端、飞书工作台嵌入应用

---

🛠️ 二、前置准备

项目	说明
飞书企业账号	需拥有开发者权限
后端服务	任意语言，用于处理OAuth2.0授权
前端H5项目	Vue/React/原生均可
公网可访问域名	开发调试可用内网穿透工具（如ngrok）

---

📱 三、第一步：创建飞书应用

1. 进入飞书开发者后台

访问 open.feishu.cn/app，使用企业账号登录。

2. 创建企业自建应用

点击 “创建企业自建应用” ，填写：

• 应用名称：例如“我的H5应用”

• 应用描述：简要说明用途

• 图标：上传应用图标（推荐144x144）

  • 

创建成功后，进入应用详情页。

---

⚙️ 四、第二步：配置应用信息

1. 获取应用凭证

在 “凭证与基础信息” 页面，记录：

• App ID

• App Secret

⚠️ App Secret 请妥善保管，仅用于服务端调用

2. 配置安全设置（关键）

在 “安全设置” 页面：

配置项	说明	示例
重定向URL	OAuth2.0授权回调地址	0ad91030-077a-451e-80b1-f692b36e6d36.wangye.domolo.cn
H5可信域名	应用H5页面所在的域名	0ad91030-077a-451e-80b1-f692b36e6d36.wangye.domolo.cn（无需http/https）

✅ H5可信域名必须与页面实际域名一致，否则无法调起飞书JSAPI

参考

---

🔧 五、第三步：配置应用能力

1. 启用网页应用能力

在 “应用功能” → “网页应用” 中：

• 开启 “网页应用” 开关

• 填写 “桌面端主页” 和 “移动端主页” URL

  • 例如：0ad91030-077a-451e-80b1-f692b36e6d36.wangye.domolo.cn/p/7zmzexemw…
  • 
  • 

2. 配置权限与事件

在 “权限管理” 页面，根据业务需求申请所需权限：

常用权限示例：

• contact:user.base:readonly - 读取用户基本信息

• contact:user.employee_id:readonly - 获取员工工号

• auth:user:phone:read - 获取手机号

💡 权限申请后需等待管理员审核（自建应用通常自动通过）

---

🔐 六、第四步：实现用户登录（OAuth2.0）

飞书H5应用使用 OAuth2.0授权码模式 获取用户身份。

1. 前端跳转授权页

// 构建授权链接
const appId = 'YOUR_APP_ID';
const redirectUri = encodeURIComponent('https://your-domain.com/callback');
const state = '随机字符串';

const authUrl = `https://open.feishu.cn/open-apis/authen/v1/index?app_id=${appId}&redirect_uri=${redirectUri}&state=${state}`;

// 跳转飞书授权页
window.location.href = authUrl;

2. 后端处理回调换取用户信息

回调接口示例（Node.js） ：

// 回调路由: /callback
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // 1. 用code换取access_token
  const tokenRes = await fetch('https://open.feishu.cn/open-apis/authen/v1/access_token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      app_id: 'YOUR_APP_ID',
      app_secret: 'YOUR_APP_SECRET',
      code: code,
      grant_type: 'authorization_code'
    })
  });
  
  const tokenData = await tokenRes.json();
  const { access_token, refresh_token, expires_in } = tokenData.data;
  
  // 2. 获取用户信息
  const userRes = await fetch('https://open.feishu.cn/open-apis/authen/v1/user_info', {
    headers: { 'Authorization': `Bearer ${access_token}` }
  });
  
  const userData = await userRes.json();
  const user = userData.data;
  
  // 3. 生成会话，返回前端
  // 可设置cookie或返回token
  res.redirect(`/index.html?userId=${user.user_id}&name=${user.name}`);
});

3. 简化方案：使用飞书JSAPI免登

如果仅需获取用户身份，可使用飞书客户端内 getUserInfo 接口：

// 需在飞书客户端内调用
window.tt?.getUserInfo({
  success: (res) => {
    console.log('用户信息', res);
    // res.user 包含用户信息
  },
  fail: (err) => {
    console.error('获取失败', err);
  }
});

⚠️ 使用JSAPI需先注入 tt 对象，且页面必须在可信域名下

---

🎯 七、第五步：接入飞书JSAPI

1. 引入JSAPI SDK

在H5页面中添加：

<script src="https://sf3-cn.feishucdn.com/js-api-sdk/v1.0.1/feishu.js"></script>

2. 注入与初始化

// 等待飞书环境就绪
document.addEventListener('DOMContentLoaded', () => {
  if (typeof window.tt !== 'undefined') {
    console.log('飞书环境已就绪');
    
    // 获取用户信息示例
    window.tt.getUserInfo({
      success: (data) => {
        document.getElementById('user-name').innerText = data.user.name;
      },
      fail: (err) => {
        console.log('请先在飞书内打开应用', err);
      }
    });
  } else {
    console.log('非飞书环境，可使用浏览器调试');
  }
});

3. 常用JSAPI接口

接口	功能
tt.getUserInfo	获取当前用户信息
tt.selectContact	选择联系人/部门
tt.openLink	打开链接（可在飞书内/外）
tt.setClipboardData	写入剪贴板
tt.showToast	提示框
tt.navigateTo	页面跳转（应用内）

---

🧪 八、第六步：本地开发与调试

1. 使用内网穿透

推荐工具：ngrok 或 cpolar

# 启动本地服务（假设端口8080）
ngrok http 8080

获得公网域名如：https://abc123.ngrok.io

2. 配置H5可信域名

将 abc123.ngrok.io 添加到飞书应用的 H5可信域名 中。

3. 飞书客户端调试

• 在飞书内搜索或打开应用

• 使用 飞书开发者工具（桌面端右键可打开调试面板）

💡 移动端调试可使用vConsole：在页面中引入 https://cdn.jsdelivr.net/npm/vconsole

---

🚀 九、第七步：发布应用

1. 版本管理与发布

在应用后台 “版本管理与发布” 页面：

1. 创建版本
2. 填写版本号、更新说明
3. 提交审核（自建应用可直接发布）

2. 上架到工作台

发布后，可在 “应用发布” 中设置应用可见范围，员工即可在飞书工作台找到该应用。

手机端访问实例：机型华为p70pro（鸿蒙6.0系统）

---

💻 十、完整示例代码

前端HTML（index.html）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
    <title>飞书H5应用示例</title>
    <script src="https://sf3-cn.feishucdn.com/js-api-sdk/v1.0.1/feishu.js"></script>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
            padding: 20px;
            background: #f5f7fa;
        }
        .card {
            background: white;
            border-radius: 16px;
            padding: 24px;
            margin-bottom: 16px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.05);
        }
        .btn {
            background: #3370ff;
            color: white;
            border: none;
            padding: 12px 24px;
            border-radius: 8px;
            font-size: 16px;
            width: 100%;
            margin-top: 12px;
        }
        .user-info {
            display: flex;
            align-items: center;
            gap: 12px;
            margin-top: 16px;
        }
        .avatar {
            width: 48px;
            height: 48px;
            border-radius: 50%;
            background: #e5e9f0;
        }
    </style>
</head>
<body>
    <div class="card">
        <h2>飞书H5应用</h2>
        <p>欢迎使用企业自建应用</p>
        <div id="userDisplay">
            <button class="btn" id="getUserBtn">获取飞书用户信息</button>
        </div>
    </div>

    <div class="card">
        <h3>JSAPI功能演示</h3>
        <button class="btn" id="toastBtn">显示提示</button>
        <button class="btn" id="copyBtn">复制文本</button>
        <button class="btn" id="openLinkBtn">打开飞书文档</button>
    </div>

    <script>
        // 等待飞书API就绪
        function ready(callback) {
            if (typeof window.tt !== 'undefined') {
                callback();
            } else {
                document.addEventListener('feishu:ready', callback);
            }
        }

        // 获取用户信息
        document.getElementById('getUserBtn')?.addEventListener('click', () => {
            ready(() => {
                window.tt.getUserInfo({
                    success: (res) => {
                        const user = res.user;
                        document.getElementById('userDisplay').innerHTML = `
                            <div class="user-info">
                                <div class="avatar" style="background-image: url(${user.avatar_url}); background-size: cover;"></div>
                                <div>
                                    <strong>${user.name}</strong><br>
                                    <span style="color: #666;">${user.user_id}</span>
                                </div>
                            </div>
                        `;
                    },
                    fail: (err) => {
                        alert('获取失败，请在飞书客户端内打开：' + JSON.stringify(err));
                    }
                });
            });
        });

        // 显示提示
        document.getElementById('toastBtn')?.addEventListener('click', () => {
            ready(() => {
                window.tt.showToast({
                    title: '这是一条提示',
                    duration: 2000
                });
            });
        });

        // 复制文本
        document.getElementById('copyBtn')?.addEventListener('click', () => {
            ready(() => {
                window.tt.setClipboardData({
                    data: '复制的内容来自飞书H5应用',
                    success: () => {
                        window.tt.showToast({ title: '复制成功' });
                    }
                });
            });
        });

        // 打开链接
        document.getElementById('openLinkBtn')?.addEventListener('click', () => {
            ready(() => {
                window.tt.openLink({
                    url: 'https://www.feishu.cn/hc/zh-CN',
                    success: () => console.log('打开成功')
                });
            });
        });

        // 检查环境
        if (typeof window.tt === 'undefined') {
            document.getElementById('userDisplay').innerHTML = '<p style="color:#ff6b6b;">⚠️ 当前非飞书环境，请在飞书客户端内打开此应用</p>';
        }
    </script>
</body>
</html>

---

❓ 十一、常见问题

Q1：JSAPI调用报错“无权限”？

• 检查H5可信域名是否配置正确

• 确认已在权限管理中申请并获取了对应权限

Q2：OAuth回调报错“redirect_uri不匹配”？

• 检查重定向URL是否与后台配置完全一致（包括端口、路径、协议）

Q3：应用在飞书内打开是空白页？

• 检查网页应用主页URL是否配置

• 检查域名是否支持HTTPS（飞书要求HTTPS）

• 打开调试面板查看报错信息

---

📝 十二、总结

通过以上步骤，你已经完成了飞书H5应用从创建到发布的完整流程：

• ✅ 创建企业自建应用

• ✅ 配置安全设置与网页应用

• ✅ 实现OAuth2.0用户登录

• ✅ 接入JSAPI调用飞书能力

• ✅ 本地调试与发布上线

下一步可以探索：

• 使用飞书机器人发送消息

• 接入飞书文档API实现内容同步

• 开发复杂业务表单与审批流程

---

📚 参考文档

• 飞书开放平台官方文档

• 飞书JSAPI接口文档

• OAuth2.0授权流程

---

本文档持续更新，如有疑问请参考飞书开放平台官方文档

岚图DMD移动管理平台 - 飞书SSO登录技术文档