本地开发：xdbapp dev
xdbapp dev 不是新的 Web 框架，也不会替换项目原有的开发命令。它先在本机准备一个短期、受权限限制的 Preview 开发环境，再把你原来的命令作为子进程启动。
# Node.js 项目：把 npm run dev 原样放在 -- 后面
xdbapp dev -- npm run dev
# Python 项目：把原启动命令原样放在 -- 后面
xdbapp dev -- python app.py
# FastAPI 示例
xdbapp dev -- python -m uvicorn app:app --reload
它自动协调什么
| 能力 | xdbapp dev 的处理方式 |
|---|---|
| Preview 环境变量 | 将通过 xdbapp env set --scope preview 保存的变量仅注入当前子进程 |
| 开放平台 | 在 127.0.0.1 启动临时代理，SDK 按需获取可续签的短期 Preview Token；不下发长期 AppSecret |
| Preview MySQL | 自动建立仅监听本机回环地址的数据库代理，并向子进程注入 DATABASE_URL |
| 当前用户 | 向 SDK 提供当前 CLI 授权用户的本地开发身份 |
| Preview 文件存储 | 注入短期 Runtime 访问凭据，SDK 通过托管 Preview 代理访问 Storage |
| 环境标识 | 注入 XDB_PAAS_APP_ID、XDB_PAAS_ENVIRONMENT=preview 等平台变量 |
以上内容只存在于当前命令及其子进程。CLI 不会创建 .env，不会修改电脑的永久环境变量，也不会在终端打印长期密钥。退出命令后，代理和临时凭据一起失效。
使用前提
- 使用管理员或开发者账号完成
xdbapp login； - 在项目根目录完成
xdbapp link； - 如果代码要读取平台能力，安装对应语言的云应用 SDK；
- 如果需要 MySQL，在
xdb-paas-deploy.yaml中声明database.provider: mysql。
SDK 请使用正式版 0.1.0 或更新版本，安装方式见SDK 概述与安装。早期 SDK 尚未接入本地身份和短期 Token，单独升级 CLI 不会更新项目依赖。
一次本地请求如何流转
应用 Preview 数据库和 Storage 与正式环境隔离；开放平台仍访问当前商家的真实业务数据，本地写接口同样可能修改真实业务。见开放平台数据边界。
它不会做什么
- 不会自动猜测并替换你的
npm run dev、python app.py等命令； - 不会让浏览器代码获得 AppSecret 或数据库密码；
- 不会连接 Production 数据库；
- 不会创建 Deployment、改变 Preview 指针或改变 Production；
- 不会完全模拟托管端的 Linux、容器、网关和资源限制。正式交付前仍应通过
xdbapp deploy验收 Preview。
常见问题
直接运行 npm run dev 和使用 xdbapp dev 有什么不同？
直接运行时，项目只能使用电脑自己已有的环境。通过 xdbapp dev 运行时，它的子进程才会获得上表中的 Preview 能力。
前端项目可以用吗？
可以。但需要秘密凭据的开放平台请求必须放在 Node.js 或 Python 后端；不能把仅存在于服务端子进程的凭据暴露给 Vite、React 或 Vue 的浏览器代码。
怎么看 CLI 实际加载了哪些能力？
xdbapp dev --debug -- npm run dev
Debug 输出会说明请求阶段和错误，但不会显示密钥值。