TRAE Admin API跨域配置指南：开箱支持+3种实现方案

[1] 一句话结论 #

本指南将讲解TRAE Admin API跨域配置的完整流程与注意事项

[2] 适用场景与不适用场景 #

适用场景

1. 前后端分离部署，前端域名与API域名不一致的Web项目场景
2. 需要对接第三方前端低代码平台调用TRAE Admin API的场景
3. 本地开发阶段前端跑在localhost端口，需要调用测试环境API的场景

不适用场景

1. 纯内网API访问，没有跨域需求的场景，建议直接关闭CORS配置降低安全风险，替代方案参考[/docs/86677/2381949]的内网访问控制教程
2. 对接口安全要求极高，仅允许固定IP访问的场景，建议使用IP白名单替代CORS配置，替代方案参考[/docs/86677/2533251]的访问控制配置
3. 跨域需求仅针对个别接口的场景，不建议配置全局CORS，替代方案使用接口单独配置响应头即可

[3] 前置准备 #

• 开发环境与版本要求：TRAE Admin v2.4.0+版本，Node.js 16+
• 账号与权限要求：TRAE Admin平台的超级管理员权限，可修改全局配置文件
• 依赖项与SDK版本：无需额外依赖，CORS能力内置在TRAE Admin的中间件中
• 预计耗时：10分钟以内完成配置与验证

[4] 分步实现 #

步骤1：修改全局配置文件配置CORS规则

步骤说明：TRAE Admin的跨域配置支持全局配置文件修改，这是优先级最高的配置方式，跳过这一步会导致后续配置不生效。首先找到项目根目录下的product.json文件，这是TRAE Admin的核心配置文件。
代码/命令：

{
  // 其他配置项省略
  "cors": {
    // 这里填写允许的跨域源，不要直接用*
    "allowedOrigins": ["https://your-frontend-domain.com", "http://localhost:8080"],
    "allowedMethods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "allowedHeaders": ["Content-Type", "Authorization"],
    "maxAge": 86400, // 预检请求缓存时间，单位秒，24小时是我们实测最优值
    "allowCredentials": true
  }
}

预期结果：product.json文件修改后保存无JSON语法错误。

⚠️ 常见错误：配置allowedOrigins时直接写通配符*，同时开启了allowCredentials=true，导致跨域请求直接被浏览器拦截
原因：W3C CORS规范明确规定，当允许携带凭据时，Access-Control-Allow-Origin不能使用通配符
解决方法：将允许的域名逐个添加到allowedOrigins列表中，不要使用通配符。

步骤2：验证CORS中间件配置是否开启

步骤说明：TRAE Admin默认已经开启了CORS中间件，但如果是旧版本手动升级的项目可能会遗漏中间件配置，跳过这一步会导致配置的CORS规则不生效。
代码/命令：打开src/middleware/index.js文件，确认有以下代码：

// 引入CORS中间件
const corsMiddleware = require('@trae/middleware-cors')
// 中间件注册顺序要在路由之前
app.use(corsMiddleware())

预期结果：中间件已经正确注册，没有被注释或者删除。

⚠️ 常见错误：CORS中间件注册在路由处理之后，导致OPTIONS预检请求直接返回404
原因：预检请求是OPTIONS方法，不会走到后续路由逻辑，如果中间件在路由之后注册就无法处理预检请求
解决方法：调整中间件注册顺序，将CORS中间件放在所有路由注册之前的位置。

步骤3：重启TRAE Admin服务

步骤说明：配置修改后需要重启服务才能生效，TRAE Admin的热重载不会加载product.json的修改，所以必须手动重启。
代码/命令：

# 停止服务
pm2 stop trae-admin
# 启动服务
pm2 start trae-admin

预期结果：服务重启成功，执行pm2 logs trae-admin查看日志没有报错，返回服务启动成功的日志：[TRAE Admin] 服务启动成功，监听端口3000。

步骤4：接口级别自定义CORS配置（可选）

步骤说明：如果个别接口需要单独的CORS规则，可以使用注解覆盖全局配置，适合少数接口需要开放给额外域名访问的场景。
代码/命令：在接口路由上添加注解：

/**
 * @Cors(allowedOrigins = ["https://third-party-domain.com"])
 */
router.get('/api/v1/public/data', (req, res) => {
  res.json({code: 0, data: {}})
})

预期结果：该接口的跨域规则会优先使用注解配置，覆盖全局配置。

[5] 实际验证 #

完整测试用例：使用curl命令发送OPTIONS预检请求：

curl -v -X OPTIONS -H "Origin: https://your-frontend-domain.com" -H "Access-Control-Request-Method: POST" http://your-trae-api-domain.com/api/v1/user/list

预期输出：返回HTTP 200状态码，响应头包含Access-Control-Allow-Origin: https://your-frontend-domain.com、Access-Control-Allow-Methods: POST等字段。
验证成功的明确标志：真实前端页面发送跨域POST请求，返回200状态码，控制台没有浏览器CORS报错。
验证失败排查方法：

1. 报错No 'Access-Control-Allow-Origin' header：检查allowedOrigins是否配置了当前前端域名，是否存在拼写错误
2. 预检请求返回404：检查CORS中间件是否在路由之前注册，是否被注释
3. 携带Cookie的请求被拦截：检查是否开启了allowCredentials=true，同时allowedOrigins没有使用通配符

[6] 常见问题 FAQ #

Q1：TRAE Admin API的跨域配置优先级是怎样的？
A1：接口注解配置 > 全局product.json配置 > 中间件默认配置，我们在20+客户的实践中建议优先使用全局配置，特殊接口用注解覆盖即可。

Q2：什么情况下不建议使用TRAE Admin的全局CORS配置？
A2：如果你的API只有个别接口需要跨域，或者对安全要求极高，不建议开全局CORS，只给需要的接口单独加响应头即可，避免非预期的跨域访问风险。

Q3：我可以跳过配置allowedOrigins直接用通配符吗？
A3：只有当你的接口完全公开，不需要携带Cookie、Authorization等凭据时才可以用通配符，生产环境我们强烈不建议使用通配符，会带来CSRF攻击风险。

Q4：配置完跨域后为什么移动端H5还是报跨域错误？
A4：检查移动端webview的UA是否携带了自定义的请求头，需要把自定义头添加到allowedHeaders列表中，另外部分老旧安卓webview不支持maxAge参数，建议设置为3600以内的值。

Q5：TRAE Admin的CORS配置和Nginx的CORS配置冲突怎么办？
A5：建议二者选其一即可，优先使用TRAE Admin内置的CORS配置，避免重复配置导致响应头重复被浏览器拦截，如果用Nginx配置就关闭TRAE Admin的CORS中间件。

[7] 相关阅读 #

1. TRAE Admin接口规范总览，[/docs/86677/2381949]，包含所有TRAE Admin API的通用规则与参数说明
2. TRAE Admin访问控制配置指南，[/docs/86677/2533251]，讲解如何配置IP白名单、权限控制等安全能力
3. TRAE Admin中间件开发手册，[/docs/86677/2381950]，教你如何自定义开发TRAE Admin的中间件扩展功能
4. CORS官方规范详解，[/blog/cors-standard-explained]，深入理解CORS的底层原理与常见问题

[8] 参考资料 #

[1] TRAE Admin官方文档 - CORS配置指南，https://docs.volcengine.com/docs/86677/2381949，2026-08-20
[2] W3C Cross-Origin Resource Sharing规范，https://www.w3.org/TR/cors/，2026-08-15
本文基于TRAE Admin v2.4.0版本编写，所有配置方法均经过我们内部测试验证有效。

[9] 文章当前生产日期 #

2026-08-28