企业官网建设流程全解析

alfred-devdocs 高级配置详解：BASE_URL、CACHE_LIFE、TEMPLATE 三大环境变量完全解读

【免费下载链接】alfred-devdocsAlfred workflow for devdocs.io项目地址: https://gitcode.com/gh_mirrors/al/alfred-devdocs

alfred-devdocs 是一款面向开发者的 Alfred workflow（工作流），它把 devdocs.io 上数百种开发文档搬进 macOS 的 Alfred 搜索框——输入doc关键字即可快速检索 CSS、JavaScript、Python 等文档并一键打开。绝大多数用户装上后只会用默认功能，却不知道 alfred-devdocs 还内置了BASE_URL、CACHE_LIFE、TEMPLATE 三个环境变量，可以彻底改变数据源、缓存策略与结果链接。本文为你带来 alfred-devdocs 高级配置详解，从零掌握三大变量的完整用法，实现内网离线、镜像加速、自定义链接等进阶玩法。

alfred-devdocs 环境变量在哪里配置？

打开 Alfred → Preferences → Workflows，选中 DevDocs 工作流，点击右上角的[x]（Workflow Configuration）按钮，就能看到BASE_URL、CACHE_LIFE、TEMPLATE三个配置项，直接在输入框填写即可，无需修改任何代码。

这三大环境变量定义在项目源码的src/info.plist的 variables 字典中（src/info.plist#L763-L771）。Alfred 运行脚本时会把它们注入为进程环境变量，PHP 端通过getenv()读取，核心代码就三行（src/scripts/devdocs.php#L21-L23）：

$this->baseUrl = getenv('BASE_URL') ?: 'https://devdocs.io/'; $this->cacheLife = (int)(getenv('CACHE_LIFE') ?: '7'); $this->template = getenv('TEMPLATE') ?: '$baseUrl$documentation/$path';

可以看到三个变量都有合理的默认值，留空也能正常使用。下面逐一解读每个变量的作用与最佳实践。

BASE_URL 环境变量：如何更换 devdocs 数据源

默认值：https://devdocs.io/

BASE_URL 是 alfred-devdocs 的数据源基地址，搜索时下载的文档列表（docs/docs.json）、各文档索引（docs/<slug>/index.json）以及最终生成的打开链接，都以它为前缀。

什么时候需要修改 BASE_URL？

• 自建 DevDocs 镜像：公司内网部署了 devdocs 私有实例，希望完全离线使用；
• 网络加速：官方站点访问慢，改用第三方加速镜像；
• 本地开发调试：本地跑了一套 devdocs 服务，想先验证效果。

设置方法与注意事项

在 [x] 配置面板把BASE_URL填为你的站点地址即可，例如http://192.168.1.100:9292/。

两个关键细节一定要记住：

1. 结尾务必保留斜杠/：源码用字符串直接拼接（如$this->baseUrl . 'docs/docs.json'），漏掉斜杠会拼出http://xxx.comdocs/...这种坏链接；
2. 管理命令仍走官方源：cdoc:add、cdoc:refresh等管理命令由src/scripts/conf.php处理，其中数据源是硬编码的官方地址（src/scripts/conf.php#L23），并不会读取 BASE_URL。也就是说：搜索与打开链接走你配置的 BASE_URL，而新增/刷新文档列表仍会请求官方站点（文档列表缓存有 7 天有效期，离线前先执行一次cdoc:refresh即可）。

CACHE_LIFE 环境变量：缓存过期时间设置

默认值：7（单位：天）

CACHE_LIFE 控制 alfred-devdocs 的缓存有效期，文档列表与每个文档的索引都会按此规则判断是否需要重新下载（判断逻辑见src/scripts/devdocs.php#L55与#L77）。

三种典型取值

小贴士：把 CACHE_LIFE 从大改小（如 7 → 0）后，下次调用就会按新规则重新下载；反之改大不会立刻清掉已有缓存，需要手动执行cdoc:refresh或删除缓存文件才能强制更新。

缓存文件由src/scripts/workflows.php#L41-L45决定存储位置（默认在 Alfred 的 Workflow Data 目录）：docs.json是文档总列表，<slug>.json是各文档的检索索引，删除对应文件即可强制重拉。

TEMPLATE 环境变量：自定义结果链接模板

默认值：$baseUrl$documentation/$path

TEMPLATE 决定按下回车后打开的 URL 长什么样。它支持 5 个占位符，在渲染结果时通过strtr()逐个替换（src/scripts/devdocs.php#L136-L144）：

典型用法

• 自建站点把版本号中的波浪号改成了横线，可用$baseUrl$docalt/$path生成兼容链接；
• 需要给链接附加统一参数或锚点时，可在模板末尾直接追加，如$baseUrl$documentation/$path?ref=workflow；
• 若模板里忘了写$baseUrl，生成的链接将不含基地址，务必检查。

另外注意：TEMPLATE留空会回退到默认模板（PHP?:的空值兜底逻辑），所以清空该项等于恢复默认行为。

组合示例：内网离线环境的完整高级配置

假设你已在内网部署了 devdocs 服务，想让 alfred-devdocs 完全离线运行，可按以下步骤一次性配置：

1. 配置 BASE_URL：填入内网地址http://192.168.1.100:9292/（注意结尾斜杠）；
2. 配置 CACHE_LIFE：填-1，让缓存永久生效，之后断网也能正常检索；
3. 配置 TEMPLATE：若内网站点 URL 结构不同，改为$baseUrl$docalt/$path等自定义模板；
4. 预热缓存：联网状态下执行一次cdoc:refresh或全局搜索，把文档列表与索引全部拉取到本地；
5. 之后完全离线使用，检索、打开文档均不依赖外网。

需要从源码研究配置逻辑时，可先获取项目代码：

git clone https://gitcode.com/gh_mirrors/al/alfred-devdocs

常见问题与排错

修改变量后不生效？确认在 [x] 配置面板保存成功；Alfred 每次运行脚本时都会重新读取环境变量，无需重启 Alfred，但修改 CACHE_LIFE 不会立刻改变已有缓存文件，需配合cdoc:refresh使用。

搜索正常但打开链接 404？优先检查 BASE_URL 结尾斜杠、TEMPLATE 占位符拼写是否正确。

代理环境下无法下载？alfred-devdocs 支持通过HTTP_PROXY（及带认证的HTTP_PROXY_AUTHORIZATION）环境变量走代理，逻辑在src/scripts/workflows.php#L495-L513，可在 Alfred 工作流环境变量中一并配置。

想恢复默认？把对应变量清空即可，三个变量都会自动回退到内置默认值。

总结

BASE_URL、CACHE_LIFE、TEMPLATE 三大环境变量让 alfred-devdocs 从"开箱即用"走向"按需定制"：BASE_URL 解决数据源问题，CACHE_LIFE 掌控缓存与离线策略，TEMPLATE 则让你完全自定义结果链接。花两分钟完成这篇高级配置，你的开发文档检索体验就能再上一个台阶 🚀

【免费下载链接】alfred-devdocsAlfred workflow for devdocs.io项目地址: https://gitcode.com/gh_mirrors/al/alfred-devdocs