Velo 后端 Web 模块（.web.js）实战：前后端解耦与外部 API 安全调用

30秒核心速览 (Executive Summary)

很多初级开发者在 Wix 中对接外部 CRM、AI 接口或短信平台时，会直接在前端页面代码（Page Code）中硬编码 API 密钥——这在浏览器“开发者工具 Network”中如同裸奔。

Wix 官方标准的生产级解法是采用 Velo Web Modules（.web.js 模块）：代码运行在隔离的 Node.js 云端沙箱中，配合 wix-secrets-backend 加密存储凭证，前端只需像调用本地函数一样通过 Promise 异步调用，彻底杜绝数据泄露与 CORS 跨域痛点。

1. 为什么关键业务逻辑必须移至后端？

前端浏览器环境永远是不可信的执行上下文。必须移入后端的场景包括：

敏感凭证保护

Stripe Secret Key、HubSpot API Token、阿里云短信密钥严禁出现在客户端 bundle 源码中。

避免 CORS 跨域拦截

很多企业内部 ERP 或自建服务未开启跨域响应头，从浏览器直接 fetch 会被同源策略阻断，而后端发起请求无此限制。

防止订单金额被篡改

商品打折计算、满减优惠券抵扣逻辑必须在服务端校验，绝不能轻信客户端上传的算后价格。

2. 什么是 Velo Web 模块（.web.js）？

在 Wix Studio 底部代码面板的 Backend（后端代码目录） 中，您可以新建以 .web.js 结尾的文件。

Velo 会自动为该文件中的导出函数（Exported Functions）生成专属的 RPC 远程调用桥梁。前端页面代码无需手写任何复杂的 REST 端点或 Fetch 请求，只要直接 import 即可使用：

// 前端页面代码可以直接像调用本地函数一样导入

import { submitLeadToCrm } from 'backend/crmIntegration.web';

$w('#submitBtn').onClick(async () => {

const result = await submitLeadToCrm({ email: $w('#emailInput').value });

console.log('CRM Response:', result);

});

3. 使用 Secrets Manager 守护敏感 API Key

在 Studio 仪表盘的「开发者工具 -> Secrets Manager（机密管理器）」中，您可以将外部服务的 Token 以 Key-Value 键值对加密保存（例如 HUBSPOT_API_KEY）。

在后端代码中，通过官方内置的 wix-secrets-backend 模块按需异步读取：

import { getSecret } from 'wix-secrets-backend';

const apiKey = await getSecret('HUBSPOT_API_KEY');

// 仅在服务端安全内存中解密，客户端浏览器绝对无法窥探

4. 实战代码：后端安全代理调用外部 REST API

以下是一个经过生产验证的完整后端 Web 模块示例（backend/crmIntegration.web.js）：

import { Permissions, webMethod } from 'wix-web-module';

import { fetch } from 'wix-fetch';

import { getSecret } from 'wix-secrets-backend';

// 声明为外部访客可调用的 Web 方法（权限可按需设为 SiteMember 或 Admin）

export const submitLeadToCrm = webMethod(Permissions.Anyone, async (leadData) => {

const token = await getSecret('CRM_BEARER_TOKEN');

const response = await fetch('https://api.yourcrm.com/v1/leads', {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'Authorization': `Bearer ${token}`

body: JSON.stringify(leadData)

});

if (!response.ok) throw new Error('CRM Sync Failed: ' + response.statusText);

return await response.json();

});

5. 实战避坑指南：CORS 跨域与权限泄露排查

避坑 1：未用 webMethod 包装导致权限越权

最新版 Velo 强制要求使用 webMethod(Permissions.xxx, async () => {}) 明确声明调用权限。若涉及内部财务、批量导出的接口错误赋予了 Permissions.Anyone，会导致安全审计不达标。

避坑 2：后端返回过多冗余敏感字段

调用第三方 CRM 返回的原始数据往往包含员工私密邮箱或内部 ID。在 return 给前端前，务必做一次数据过滤（Pick/Omit），仅返回前台展示必需的字段。

6. Wix 官方 Support 权威参考文档

关于服务端 Web 模块与第三方接口集成的官方规范：

Velo: Web Modules - Writing Server-Side CodeOfficial Support

官方关于在 .web.js 中编写 Node.js 服务端函数并无缝暴露给前端的完整规范。

Velo: Storing Sensitive Information with the Secrets ManagerOfficial Support

如何使用 Secrets Manager 安全加密存储第三方 API 密钥与 Access Token。

Velo: Accessing Third-Party Services with the Fetch APIOfficial Support

如何在服务端使用 wix-fetch 绕过浏览器同源策略限制，安全对接外部 CRM 与支付网关。

7. 高频常见问题解答 (FAQ)

Q：后端 Web 模块有超时时间限制吗？

有的。Velo 服务端函数的 HTTP 请求超时上限默认为 14 秒。如果对接的外部大模型或数据导出任务耗时超过 14 秒，建议使用 Webhook 异步回调或任务队列机制。

Q：.web.js 文件与普通的 .js 后端文件有什么区别？

.web.js 是专门暴露给前端直接异步调用的 Web 模块；而普通 .js 后端文件（如 data.js 或自定义工具库）只能被其他后端文件引用，绝对无法从前端页面代码直接访问，安全性更高。