★ FEATURED ARTICLE 【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载Blume 是一个面向人类与 AI 代理的开源文档框架本文带你完成 Blume 文档站点部署一条命令生成纯静态 HTML零配置托管到任意静态主机或一行代码接入 Vercel、Netlify、Cloudflare、Node 服务端渲染覆盖绝大多数部署场景。 30 秒理解 Blume 的部署模型Blume 的部署思路非常清爽先记住两个事实默认就是静态站blume build会把你的文档编译成纯 HTML、CSS 和本地搜索索引全部落在dist/目录里不需要运行任何服务端进程需要动态能力时再点名主机在配置里写一个适配器如vercel()构建产物自动切换为该平台的服务器输出。项目值构建命令blume build输出目录distNode 版本22.19 或更高也就是说Vercel、Netlify、Cloudflare Pages、GitHub Pages 甚至任意对象存储/CDN只要把上面三行填进后台就能跑起来。 静态部署零配置托管到任意主机blume build完成后dist/目录里已经包含了一份完整的网站每个文档页和自定义页的静态 HTML本地搜索索引默认 Orama可选 Pagefind已知站点 URL 时自动生成sitemap.xml和robots.txt给 AI 工具用的llms.txt与llms-full.txt重定向页面以及开启后的预渲染 Open Graph 图片。把dist/指向任何静态托管服务网站就跑起来了。关键一步设置站点 URLSitemap、canonical 标签、RSS、Open Graph 图片都需要一个绝对的站点地址。好消息是Vercel / Netlify / Cloudflare Pages构建时自动从平台环境变量检测零配置其他主机GitHub Pages、S3、自建 CDN在 blume.config.ts 中显式设置deployment: { site: https://docs.example.com, }两个细节值得注意Vercel 和 Netlify 的自动检测优先选择稳定的生产域名而非每次部署的预览 URL所以 canonical 地址不会随部署漂移Cloudflare Pages 只暴露当前部署的 URL每次部署都会变因此必须手动设置siteCloudflare Workers 同理。本地blume dev时会自动回退到http://localhost:4321但正式构建绝不会指向 localhost。⚙️ 部署到子路径Subpath Deploys文档挂在example.com/docs这类子路径下设置base即可GitHub Pages 项目站点最常见deployment: { base: /docs, }整个站点包括根路径都会移到 base 之下内部链接、静态资源、甚至你在 HTML 里手写的根相对href/src都会被自动改写。小技巧blume.config.ts是一个 JS 模块所以base可以直接来自环境变量如process.env.DOCS_BASE。这样 CI 可以为每个 Pull Request 的预览站点生成独立子路径生产环境什么都不用改。 注意区分deployment.base是整个应用挂在主机的哪个子目录basePath则是把文档路由挂到/docs这类路径段下但侧边栏保持扁平两者可以组合使用最终页面路径为{deployment.base}/{basePath}/page。☁️ 服务端渲染一行代码接入 Vercel、Netlify、Cloudflare静态产物能覆盖绝大多数文档场景。当你需要请求时功能——最典型的是 AI 助手 端点和 MCP 服务器——只需在配置里点名主机import { vercel } from blume/deploy; export default defineConfig({ deployment: vercel(), });四个适配器一览适配器底层包适用场景vercel()astrojs/vercelVercel体验最完善的路径netlify()astrojs/netlifyNetlify Functionsnode()astrojs/node自托管 Node 服务器、容器cloudflare()astrojs/cloudflareCloudflare Workers几个实用要点vercel()和node()随 Blume 内置开箱即用netlify()和cloudflare()需要先安装对应包缺失时blume build会停下并告诉你该运行什么安装命令blume doctor也会报告每个适配器都接受相同的命名参数site、base、output其余参数原样透传给底层astrojs/*适配器只想保留静态构建、又想要平台检测能力传output: static即可例如netlify({ output: static })node()适配器产出一个独立服务器node dist/server/entry.mjs直接运行默认监听localhost:4321可用HOST/PORT环境变量覆盖记得连同node_modules一起部署不能只拷dist/cloudflare()构建在blume build之后执行npx wrangler deploy即可完成部署Blume 会自动生成重定向后的 Wrangler 配置并把.wrangler/加入.gitignore。本项目自己的文档站就采用了这种模式配置见 apps/docs/blume.config.ts// Server output (MCP server) on Cloudflare Workers via astrojs/cloudflare. deployment: cloudflare({ site: https://useblume.dev }),⚡ 额外福利在 Vercel 和 Cloudflare 上服务端构建会自动开启Accept: text/markdown内容协商——AI 代理带该请求头访问任意文档页时会得到同一 URL 下的原始 Markdown 版本。这对面向代理的文档框架来说是很自然的加分项。 重定向静态与服务端通吃在 blume.config.ts 中声明式地映射新旧 URLredirects: [{ from: /old, to: /new, status: 301 }],status支持301、302、307、308默认 301。Blume 的聪明之处在于同时照顾不同主机的差异服务端构建在请求时按配置的状态码应答blume dev和blume preview同样如此静态构建则双管齐下既生成重定向页面又写出各平台认的文件——Netlify/Cloudflare 读_redirectsVercel 读vercel.json未指定主机时两者都写外加一份blume-redirects.json结构化清单方便你给 nginx/Apache 或自建边缘 Worker 使用。模式重定向同样支持 Mintlify /vercel.json风格的写法redirects: [ { from: /beta/:slug*, to: /v2/:slug* }, { from: /blog/:slug, to: /articles/:slug }, ]:name匹配一个完整路径段:name*作为最后一段可匹配剩余任意层级精确规则优先于模式规则模式之间按声明顺序匹配。两个平台差异值得记住Netlify存在同名文件的 URL 会优先于重定向规则Blume 生成的_redirects会自动加上强制标志301!VercelGit 连接的项目只读项目根目录的vercel.json不会读dist/里那份。把dist/vercel.json里的redirects和headers拷到根目录即可或者直接用vercel()服务端构建。发布前用blume validate检查每条重定向的落点blume audit会在构建产物中完整追踪每条重定向链路。 私有文档用主机的访问保护Blume 本身不做登录。静态构建就是纯文件能访问主机的人就能拿到dist/里的一切。正确做法是打开主机的访问保护VercelDeployment Protection选 All Deployments 范围覆盖生产而非仅预览Netlify密码保护或团队登录CloudflareCloudflare Access按邮箱、邮箱域名或账户成员放行自建服务器在dist/前加认证层如 nginxauth_basic。保护对服务端构建同样生效且覆盖全站页面、搜索索引、.md副本、llms.txt、Open Graph 图片全部在保护之内。 Monorepo 与其他主机Monorepo把文档工作区作为独立项目部署将主机的根目录Vercel 的 Root Directory / Netlify 的 Base directory指向它。在 Vercel 上若文档会读取工作区之外的文件组件示例、theme.css中的source路径、仓库其他位置的 spec 文件等保持Include source files outside of the Root Directory开启。S3 CloudFront需要两样额外配置——一个把/quickstart映射到/quickstart/index.html的 CloudFront Function以及上传时设置正确 Content-Type 的上传脚本。dist/_headers列出了构建所需的全部规则。构建缓存Vercel 和 Netlify 都会恢复node_modules因此渲染过的 OG 卡片可以跨部署复用Cloudflare Workers Builds 只持久化node_modules/.astro不保留node_modules/.cache。安装命令请用npm install/bun install/pnpm install而不是npm ci——后者会删掉整个node_modules缓存前功尽弃。环境变量功能缺密钥时blume dev/build会提前警告如助手的AI_GATEWAY_API_KEY、限流的UPSTASH_REDIS_REST_URL等让问题在构建阶段暴露而不是第一个请求到来时。本地放.env.local生产配到主机环境变量里。✅ 部署前自查清单blume buildblume preview在生产之前按静态主机的行为完整预览一次包括重定向和尾斜杠处理确认site自动检测或手动设置保证 canonical 与 sitemap 正确blume validate校验重定向blume doctor体检依赖每次构建结束都会打印构建摘要——输出模式、适配器、解析后的站点 URL、搜索提供商、重定向数量、sitemap 状态——部署前花十秒扫一眼确认发出的正是你想要的那个站点。更多细节内容类型、Powered-by 响应头等见官方部署文档 02-deployment.mdx适配器源码在 packages/blume/src/deploy/adapters/。赞分享【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载相关推荐Sunshine 自托管游戏串流指南4 步从装包到 Moonlight 出画面Sunshine 自托管游戏串流指南4 步从装包到 Moonlight 出画面 Sunshine 是一款开源免费的自托管游戏串流主机游戏跑在你自己的电脑上音视频后端Slidev 幻灯片构建与部署完整指南从 slidev build 静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管Slidev 幻灯片构建与部署完整指南从 slidev build 静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管前端开发工具BentoPDF 静态托管实战指南基于 Netlify、Vercel 与 GitHub Pages 的自托管部署与 SEO 控制BentoPDF 静态托管实战指南基于 Netlify、Vercel 与 GitHub Pages 的自托管部署与 SEO 控制 BentoPDF 是一款「隐前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
