后端
应用可以带一个后端: 一个导出 fetch 的模块, 或任何调 listen() 的 Node.js / Bun 服务器 (Express、Hono、Fastify ……). 页面用普通的 fetch('/api/…') 访问它.
应用后端在 macOS、Linux 和 Windows 上都能跑. Windows 上运行时用另一种方式连到后端; 见 Windows 上.
写一个后端
写一个后端 一节的链接acdev new my-app --backend 生成的 server.ts:
export default { fetch(request: Request): Response { const url = new URL(request.url) if (url.pathname === '/api/hello') return Response.json({ hello: 'world', at: new Date().toISOString() }) return new Response('not found', { status: 404 }) },}页面里:
const answer = await (await fetch('/api/hello')).json()export default { fetch } 在 Bun 和 Node.js 上都能用: Node.js 上 acdev 的 preload 用 node:http 把它跑起来, 请求和回应都是 WHATWG 的 Request / Response, 支持流式 body. (Node.js 上没有 WebSocket 升级.)
也可以自己 listen:
import { createServer } from 'node:http'
createServer((req, res) => res.end('hi')).listen(3000)后端出页面
后端出页面 一节的链接要让后端自己渲染页面 (用 Hono、JSX、模板 ……在服务端生成 HTML, 不用 acdev 认得的框架), 把入口设成 /:
{ "type": "app", "id": "my-app", "label": "My app", "icon": "app", "entry": "/" }这时窗口从后端打开 /, 它跳到的每个页面 (链接、location.href、表单) 也都来自后端; public/ 仍然在应用的根路径下提供. 没有后端时, acdev check 和 acdev build 报错停下; 以 / 结尾的入口只接受 / 这一个. 在服务端渲染的框架 (Next.js、Nuxt、SvelteKit ……) 自动这样设置; 见 前端框架.
入口
入口 一节的链接不写 backend 时, acdev 按顺序找第一个存在的:
server.ts server.js src/server.ts src/server.js server/index.ts server/index.js backend/index.ts backend/index.js
显式指定, 或关掉:
{ "backend": { "entry": "api/main.ts", "port": 8080 } }{ "backend": false }port 默认 3000, 是后端以为自己在听的端口.
后端不占 TCP 端口
后端不占 TCP 端口 一节的链接应用的后端不在宿主机上开 TCP 端口. 构建时 acdev 在后端旁放一个 preload (acde-listen.js), 它把 Bun.serve、Bun.listen 和 net / http / https / tls / http2 的 listen(P) 都换成一个 unix socket <应用的 socket 目录>/P.sock. 没给端口时取 PORT / BUN_PORT / NODE_PORT, 否则用 3000.
所以:
- 两个应用都
listen(3000)不会冲突. - 页面访问同源的路径 (
/api/x), 或http://localhost:<端口>/…(以及127.0.0.1、[::1]、0.0.0.0), 都会送到自己的后端. - 指定端口的 UDP
bind会被拒绝 (EACCES); 原生扩展自己开的端口不受此限制.
Windows 上
Windows 上 一节的链接同一份构建产物在 Windows 上也能跑, 那里后端同样不开 TCP 端口, 也不开命名管道. 运行时怎么连到它, 看是什么在跑它:
- Bun: 和 macOS、Linux 上一样,
listen(P)变成一个 socket 文件P.sock. 它所在的目录 (ACDE_APP_SOCKETS) 每次启动后端时重新建, 只有当前用户和系统能打开. - Node.js: Node.js 在 Windows 上不能听 socket 文件, 所以根本没有东西在听. preload 留住调了
listen(P)的那个服务器, 运行时通过一条通到后端进程的私有管道, 把每个连接 (HTTP 请求和 WebSocket 升级) 交给它. 后端拿到ACDE_APP_CHANNEL=fd, 没有ACDE_APP_SOCKETS. 在这之前的 acdev 构建的后端在 Windows 上不会被启动; 日志里写not started: acde-listen.js does not support the Windows channel (built by an older acde: acdev build it again).
在 Windows 上停后端时, 运行时请它自己关闭: 它不再接新连接, 做完进行中的请求, 然后退出; 3 秒后运行时结束它, 连同它启动的进程.
打包
打包 一节的链接acdev build 把后端打成单个 ES 模块 backend/server.js (target node): npm 包打进去, Node 内置模块和 bun / bun:* 保留为导入. Bun 和 Node.js 都能跑同一份产物.
运行
运行 一节的链接- 应用的第一个窗口打开时启动后端, 最后一个窗口关掉时停掉 (macOS 和 Linux 上先 SIGTERM, 3 秒后 SIGKILL; Windows 见 上文). 一分钟里崩溃第 4 次后不再自动重启.
- PATH 上有
bun时用 Bun 跑, 否则用 Node.js (≥ 22.3).acdev dev按工程的 JS 运行时选. - 环境变量是新建的:
ACDE_APP_ID、ACDE_APP_DATA、ACDE_APP_SOCKETS、PORT、NODE_ENV=production, 再加会话的HOME、PATH、LANG等, 以及下面说的代理变量. 除此之外不会继承你终端里的环境. - 代理设置会传给后端. 会话里设了
http_proxy、https_proxy、all_proxy中的任何一个时, 后端拿到会话里的http_proxy、https_proxy、all_proxy和no_proxy, 原样不变 (macOS 和 Linux 上小写和大写两种名字都按设的传; Windows 上变量名不分大小写, 用大写的名字). 一个都没设时, 后端拿到系统的手动代理, 和页面用的是同一份设置. 只有 Windows 和 macOS 有这种设置: Windows 上是用户 Internet 设置里的 HTTP 代理 (socks=项变成all_proxy=socks4a://host:port), 用大写的名字设; macOS 上是网络设置里的 HTTP、HTTPS 和 SOCKS 代理 (SOCKS 变成socks5h://host:port), 小写和大写两种名字都设. 这时no_proxy里是会话的no_proxy、换成no_proxy写法的系统例外 (*.example.com变成.example.com,192.168.*变成192.168.0.0/16; 其它通配符、Windows 的<local>和 macOS 的「排除简单主机名」没有no_proxy的写法, 不带上), 以及localhost,127.0.0.1,::1. 代理自动配置脚本和自动发现代理是按 URL 回答的, 没法写成变量, 所以用它们时后端拿不到系统代理 (Windows 上只勾了「自动检测设置」时, 手动代理照样传). 每次启动后端时读一遍这些设置. Linux 没有可读的系统代理设置: 那里只算会话的变量. 你用的 HTTP 客户端还得自己认这些变量 (Bun 的fetch和很多 npm 客户端认; Node.js 内置的fetch默认不认). - 工作目录是
$XDG_DATA_HOME/acde/apps/<id>/, 可以在这里放应用自己的数据. - 在 macOS 和 Linux 上, socket 放在会话的运行时的一个目录里 (
ACDE_APP_SOCKETS). 每个会话有自己的目录, 在 acdev 的运行时目录下的<运行时的 pid>/<id>, 后端停了就删掉: macOS 上是$TMPDIR/acde-<uid>, 别处是XDG_RUNTIME_DIR里的acde/(Linux 上没设时是/run/user/<uid>). socket 路径比系统允许的长 (macOS 104 字节, Linux 108) 时后端不启动, 日志里会说. - 后端的输出进运行时的日志, 前缀
[<id>#backend].acdev dev会把它打在终端里.
直接跑
直接跑 一节的链接不经运行时单独调试构建好的后端时, 给它一个 socket 目录, 并载入 acdev build 放在它旁边的 preload (下面的命令是 macOS 和 Linux 上的):
acdev buildcd .acde/backendACDE_APP_SOCKETS=/tmp/my-app-sockets bun --preload ./acde-listen.js server.jscurl --unix-socket /tmp/my-app-sockets/3000.sock http://localhost/api/hello