服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Wrangler 4.148.0 及以上可用 assets.base_path；cloudflare.config.ts 项目使用 worker.assets.basePath，并要求 cf 1.0.0-beta.13 及以上。
- 设置 /blog 后，构建文件仍可放在 dist 根目录；文档示例将 /blog/ 映射到 dist/index.html。
- Worker 的路由也必须覆盖 /blog 前缀；只有 example.com/api/* 的路由不会处理 /blog/ 请求。
- 使用 Cloudflare Vite 插件时同步设置 Vite 的 base；_headers、_redirects、assets.run_worker_first 和自建 Assets binding 请求都要考虑完整公开路径。
网址前缀与磁盘目录是两件事
Cloudflare 于 2026 年 11 月 11 日公布，Worker 的静态资源现在可以通过网址前缀提供，例如把站点内容挂在 example.com/blog/ 下，而构建产物仍保留在 assets.directory 的根目录。设置 base_path 后，不必为了匹配公开网址而额外把文件嵌套进名为 blog 的子目录。
理解时可以把它分成两层：assets.directory 指向实际构建输出所在的磁盘目录，base_path 则声明这些文件通过哪个公开 URL 前缀访问。配置只改变静态资源对外呈现的路径；应用自己的路由、Worker 路由和构建时写入页面的资源地址仍要彼此匹配。
先选项目正在使用的配置入口
如果项目使用 Wrangler，版本需为 4.148.0 或更新版本，并在 assets 配置中设置 base_path。目录仍指向原有输出，例如 assets.directory 为 ./dist、assets.base_path 为 /blog。Wrangler 支持 JSON、TOML 等配置格式，具体语法按项目现有文件书写。
如果项目使用 cloudflare.config.ts，则在 Worker 配置中使用 worker.assets.basePath；Cloudflare CLI cf 需为 1.0.0-beta.13 或更新版本。先确认实际执行的 CLI 与版本，再采用对应的键名。不要把 Wrangler 的下划线写法和 cloudflare.config.ts 的驼峰写法混到同一个配置示例里。
把根目录里的构建文件映射到 /blog/
假设 dist 中有 index.html、posts/post1.html 和 posts/post2.html，并将资产目录设为 dist、公开前缀设为 /blog。Cloudflare 文档给出的映射是：访问 example.com/blog/ 会提供 dist/index.html，访问 example.com/blog/posts/post1 会提供 dist/posts/post1.html。
这个例子展示的是公开路径与现有文件路径之间的映射，不要求把构建输出复制到 dist/blog。配置前先检查构建产物的实际相对路径，再对照希望访问的 URL。若应用自身生成绝对路径或重写规则，也要确认它们是否仍指向预期的 /blog/ 地址。
让 Worker 路由覆盖同一个前缀
静态资源配置和 Worker 路由需要一起核对。Cloudflare 指出，Worker 的 routes 必须包含 base path；例如 Worker 只绑定 example.com/api/* 时，访问 example.com/blog/ 的请求不会到达该 Worker，也不会到达该 Worker 上的静态资源。需要由 Worker 处理这些请求时，应确认路由匹配范围包括 /blog/。
反过来，/blog 以外的请求不会解析为这组静态资源；只有存在匹配路由时，Worker 才会处理该请求。排查 404 或意外落入 Worker 时，先分别记录请求 URL、Worker route 和 assets.base_path，再判断请求是否同时满足所需的匹配范围，不要只检查文件是否存在。
同步 Vite 与资源规则中的公开路径
如果通过 Cloudflare Vite 插件构建，还要将 Vite 的 base 设为 /blog/。Vite 生成的脚本、样式或其他资源引用也需要与挂载后的公开地址一致。只设置 Cloudflare 的 base_path，不能替代构建工具对页面资源 URL 的配置。
Cloudflare 文档说明，_headers、_redirects 和 assets.run_worker_first 中的路径都使用公开 URL 路径，因此示例需要包含 /blog。维护这些规则时，应把前缀视作路径的一部分，一并检查静态资源、重定向和交由 Worker 处理的路径是否对应同一公开 URL。
排查 Assets binding 的路径与 404
通过 Assets binding 请求资源时，同样使用挂载后的公开路径。Cloudflare 给出的示例是 env.ASSETS.fetch("https://assets.local/blog/posts/post1")；如果代码自行构造请求，要把 /blog 放进 pathname。将原始请求直接转发给 Assets binding 时，文档说明可以保持原请求不变。
出现问题时，可按顺序核对 CLI 及版本、实际生效的配置键、构建文件相对路径、base_path、Worker route、Vite base，以及 _headers、_redirects 和 assets.run_worker_first 中的完整路径。本文依据 Cloudflare 2026 年 11 月 11 日发布的说明与指南整理，没有检查任何具体账户、项目配置或部署结果。
资料来源
常见问题
设置 /blog 后，还需要创建 dist/blog 目录吗？
不需要。该功能允许构建文件留在 assets.directory 根目录，再由 base_path 将它们挂载到 /blog 等公开 URL 前缀。
Worker 只有 example.com/api/* 路由，能处理 /blog/ 静态资源吗？
不能。Cloudflare 说明 Worker 路由必须包含所用 base path；只匹配 /api/* 的路由不会覆盖 /blog/ 请求。
使用 Cloudflare Vite 插件时只设置 base_path 可以吗？
不够。Cloudflare 还要求将 Vite 的 base 设为对应公开前缀，例如 /blog/，以便构建出的资源 URL 与挂载路径一致。