Back to Details

http-endpoints

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HTTP Endpoints

HTTP 端点

HTTP vals (
fileType: "http"
) export a request handler and run on every incoming HTTP request. Each HTTP file is assigned a live URL — never construct it yourself; read 
links.endpoint
from 
list_files
or 
create_file
responses, or call 
fetch_val_endpoint
.
That URL is open to anyone unless the val's app access (
httpPrivacy
) is 
restricted
, in which case unauthenticated callers get a 
302
to a login page instead of your response — see the 
restricted-access
skill.
HTTP val（
fileType: "http"
）会导出一个请求处理器，针对每个传入的 HTTP 请求运行。每个 HTTP 文件都会被分配一个实时 URL——请勿自行拼接构造；请从 
list_files
或 
create_file
的返回结果中读取 
links.endpoint
，或调用 
fetch_val_endpoint
获取。
该 URL 默认对所有人开放，除非 val 的应用访问权限（
httpPrivacy
）设为 
restricted
——这种情况下，未认证的调用者会收到 
302
重定向到登录页，而非你的响应内容，详见 
restricted-access
技能。

Basic handler

基础处理器

ts
// Learn more: https://docs.val.town/vals/http/
export default async function (req: Request): Promise<Response> {
  return Response.json({ ok: true });
}
The file must have an 
export
— 
export default
for the handler.
ts
// Learn more: https://docs.val.town/vals/http/
export default async function (req: Request): Promise<Response> {
  return Response.json({ ok: true });
}
文件必须包含 
export
语句——处理器需使用 
export default
导出。

Hono

Hono

When using Hono, export 
app.fetch
(not 
app
):
ts
import { Hono } from "npm:hono";
import { parseVal, serveImmutableFile } from "https://esm.town/v/std/utils/index.ts";

const app = new Hono();

app.get("/", (c) => c.text("hello"));

// Immutable asset caching (see the client-side-js skill): serves the
// current-version URLs your HTML shell stamps with immutableFileUrl()
app.get("/__immutable/*", (c) => serveImmutableFile(c.req.path));

// View source redirect
app.get("/source", (c) => c.redirect(parseVal().links.self.val));

// Always add this for full stack traces on errors:
app.onError((err) => Promise.reject(err));

export default app.fetch;
Hono's 
serveStatic
does not work on Val Town. Use 
serveFile
/ 
staticHTTPServer
from 
std/utils
for static files. For the full 
std/utils
API (
readFile
, 
serveFile
, 
staticHTTPServer
, 
listFiles
, 
listFilesByPath
, 
httpEndpoint
, 
parseVal
, …), fetch 
https://utilities.val.run/docs.md
.
使用 Hono 时，请导出 
app.fetch
（而非 
app
本身）：
ts
import { Hono } from "npm:hono";
import { parseVal, serveImmutableFile } from "https://esm.town/v/std/utils/index.ts";

const app = new Hono();

app.get("/", (c) => c.text("hello"));

// Immutable asset caching (see the client-side-js skill): serves the
// current-version URLs your HTML shell stamps with immutableFileUrl()
app.get("/__immutable/*", (c) => serveImmutableFile(c.req.path));

// View source redirect
app.get("/source", (c) => c.redirect(parseVal().links.self.val));

// Always add this for full stack traces on errors:
app.onError((err) => Promise.reject(err));

export default app.fetch;
Hono 的 
serveStatic
无法在 Val Town 上运行。静态文件请使用 
std/utils
中的 
serveFile
/ 
staticHTTPServer
。如需完整的 
std/utils
API 文档（
readFile
、
serveFile
、
staticHTTPServer
、
listFiles
、
listFilesByPath
、
httpEndpoint
、
parseVal
等），请访问 
https://utilities.val.run/docs.md
。

CORS

CORS

Val Town adds permissive CORS headers by default (
Access-Control-Allow-Origin: *
), so in 99% of cases, you should never need to do anything with CORS. Using Hono's 
cors
middleware is almost always unnecessary.
If you set any CORS header yourself, Val Town stops adding all default headers — so either handle CORS completely yourself or don't touch it at all.
Val Town 默认会添加宽松的 CORS 头（
Access-Control-Allow-Origin: *
），因此 99% 的场景下你无需处理 CORS 相关配置。使用 Hono 的 
cors
中间件几乎是不必要的。
如果你自行设置了任何 CORS 头，Val Town 就会停止添加所有默认头——因此要么完全自行处理 CORS，要么完全不要修改相关配置。

Redirects

重定向

Response.redirect
is broken on Val Town. Use one of:
ts
return new Response(null, { status: 302, headers: { Location: "/path" } });
// or, with Hono:
return c.redirect("/path");
Response.redirect
在 Val Town 上存在问题，请使用以下任一方式：
ts
return new Response(null, { status: 302, headers: { Location: "/path" } });
// or, with Hono:
return c.redirect("/path");

What's not available

不支持的功能

  • WebSockets: Val Town does not accept incoming WebSocket connections. Use polling, long polling, or server-sent events instead.
  • Filesystem access: see the platform constraints. For persistent state, use 
    std/sqlite
    or 
    std/blob
    .
  • WebSockets：Val Town 不接受传入的 WebSocket 连接。请使用轮询、长轮询或服务器发送事件（SSE）替代。
  • 文件系统访问：详见平台约束。如需持久化状态，请使用 
    std/sqlite
    或 
    std/blob
    。

Surfacing client-side errors

上报客户端错误

For HTML responses, add this script tag to send browser errors back to val logs (visible via 
get_logs
):
html
<script src="https://esm.town/v/std/catch"></script>
对于 HTML 响应，添加以下 script 标签可将浏览器错误回传到 val 日志（可通过 
get_logs
查看）：
html
<script src="https://esm.town/v/std/catch"></script>

Verifying changes

验证变更

After editing an HTTP val, fetch it to confirm it returns the expected HTTP response. Do not report a change as done without this step.
编辑 HTTP val 后，请发起请求确认其返回符合预期的 HTTP 响应。未完成此步骤请勿宣称变更已完成。