Categories
Tags
Ai 生成 API学习 API简化 api请求 API调用 best-practices Blogging Caching catchTag catchTags class CLI Config context Context Context.Tag CSS Customization Demo development DocC dual API effect Effect Effect.Service Effect.succeed Example extension filterOrFail flatMap Fuwari gen generator grep hooks HTML HTTP响应 IDE自动补全 iOS javascript JavaScript Javascript Layer.effect Layer.provide Layers Linux Markdown Mock Next.js ParseError pipe pokemon PostCSS process.env progress Promise promise provideService PWA react React React Hook Form React Query React Router react-native Scheduler Schema Schema.Class security Service Worker Services SSR state-management suspense Tagged Errors TaggedError TanStack Query TanStack Start tips tryPromise tsconfig TypeScript typescript Video VS Code vscode Web API Web Development yield Zod 不透明类型 二叉树 代码组织 任务调度 优先级 使用服务 依赖注入 依赖管理 值语义 入门教程 最佳实践 最小堆 函数式编程 函数组合 前端 前端开发 副作用 副作用控制 可视化 可组合性 可维护性 可访问性 命令行 响应过滤 多个错误 实现 实践指南 层 层依赖 层组合 工具链 并发控制 应用架构 延迟执行 开发技巧 开发教程 开源 异步处理 异步操作 异步编程 性能优化 手写系列 排序 接口设计 插件开发 数据结构 数据获取 数据解码 数据验证 无限滚动 日历 日志分析 服务 服务依赖 服务定义 服务实现 服务提供 测试 源码分析 状态管理 环境变量 生成器 离线支持 程序分离 算法 类型安全 类型定义 类型推断 类型系统 类定义 线性代码 组合 翻译 自定义错误 表单验证 记忆化 设计模式 语义化 运维 运行时验证 部分应用 配置 配置变量 配置服务 配置管理 重构 错误处理 错误定义 错误恢复 项目设置
1142 words
6 minutes
解决iOS文档绝对路径问题的CLI工具
解决iOS文档绝对路径问题
为了解决iOS生成document绝对路径不匹配线上服务器路径的问题,我为iOS团队开发了一个脚手架工具解决了这个问题。
项目目标
- 解决DocC文档绝对路径问题
- 开发简单易用的CLI工具
- 支持批量处理多个文档
- 添加自动化测试
素材准备
项目地址:SlothCreatorBuildingDocCDocumentationInXcode

如图所示,随后生成了SlothCreator.doccarchive这个包,这个就是我的目标。
问题分析
预期表现(点击展开)
➜ Debug cd SlothCreator.doccarchive ➜ SlothCreator.doccarchive pnpx http-server Starting up http-server, serving ./ http-server version: 14.1.1 http-server settings: CORS: disabled Cache: 3600 seconds Connection Timeout: 120 seconds Directory Listings: visible AutoIndex: visible Serve GZIP Files: false Serve Brotli Files: false Default File Extension: none Available on: http://127.0.0.1:8080 http://192.168.6.207:8080 Hit CTRL-C to stop the server
然后访问http://127.0.0.1:8080/documentation/slothcreator,展示的效果同Xcode,符合预期:

项目根路径改变后
当我们改变项目根路径后:
^Chttp-server stopped. ➜ SlothCreator.doccarchive cd ../ && pnpx http-server Starting up http-server, serving ./ http-server version: 14.1.1 http-server settings: CORS: disabled Cache: 3600 seconds Connection Timeout: 120 seconds Directory Listings: visible AutoIndex: visible Serve GZIP Files: false Serve Brotli Files: false Default File Extension: none Available on: http://127.0.0.1:8080 http://192.168.6.207:8080 Hit CTRL-C to stop the server
页面打开失败:

控制台错误信息:
GET http://127.0.0.1:8080/js/chunk-vendors.bdb7cbba.js net::ERR_ABORTED 404 (Not Found) GET http://127.0.0.1:8080/css/index.3a335429.css net::ERR_ABORTED 404 (Not Found) GET http://127.0.0.1:8080/js/index.0d775bb6.js net::ERR_ABORTED 404 (Not Found)
根本原因
既然找不到资源,那么直接打开文件夹去查找静态资源,一查直接定位根本原因:绝对路径!

解决方案:在当前环境下,只需将
/js/[index.0d775bb6.js]这类模式的静态资源全部替换成/SlothCreator.doccarchive/js/[index.0d775bb6.js]即可。
尝试手动修复
直接通过IDE的replace All功能修复一版本, 发现问题依旧存在。部分资源是js动态注入的. 
灵光一闪,先试试看xcode自带的工具转换的是啥格式的,然后我的js逻辑再照抄不就行了吗(官方工具之所以没有在内部项目使用,是因为在复杂项目中有bug, 并且issue仍然未被修复)
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc process-archive transform-for-static-hosting SlothCreator.doccarchive \ --hosting-base-path /SlothCreator.doccarchive
替换完成后,通过IDE搜索SlothCreator.doccarchive

这里能分析出两个问题
- 处理对象有且仅有
html文件. - 处理pattern除了js和css, 还有
baseUrl = "/"这种pattern.
CLI 工具开发方案
使用的技术栈
| 工具 | 用途 | 版本 |
|---|---|---|
cac | 命令行参数解析 | ^6.7.14 |
fs-extra | 增强的文件系统操作 | ^11.3.0 |
tsup | TypeScript打包工具 | ^8.4.0 |
typescript | 开发语言 | ^5.8.2 |
实现步骤
初始化项目
mkdir path-fixer && cd path-fixer npm init -y npm i cac fs-extra npm i -D typescript tsup @types/fs-extra创建主要功能模块 项目结构分为三个主要文件:
index.ts: 命令行入口和主流程replacer.ts: 路径替换核心逻辑logger.ts: 日志处理功能
发布到npm
# 构建项目 npm run build # 发布到npm npm publish --access=public
使用示例
# 安装 npm install -g @0bipinnata0/path-fixer # 使用 path-fixer fix ./SlothCreator.doccarchive --base-url=/SlothCreator.doccarchive # 显示详细日志 path-fixer fix ./SlothCreator.doccarchive --base-url=/SlothCreator.doccarchive --verbose
或者
pnpx @0bipinnata0/path-fixer fix ./SlothCreator.doccarchive --base-url=/SlothCreator.doccarchive
修复后的效果

补充说明
NOTE此工具仅适用于DocC生成的文档,其他类型的文档可能需要不同的处理方式。
TIP如果你遇到类似问题,可以考虑使用此工具或参考其实现原理。
WARNING在生产环境中使用前,请务必进行充分测试!
代码实现核心部分
// 核心替换逻辑 export function replaceAbsolutePaths(filePath: string, baseUrl: string, logger: ILogger = defaultLogger): string | null { try { const content = fs.readFileSync(filePath, 'utf8'); // 标准化 baseUrl,确保前后都有且仅有一个斜杠 const normalizedBaseUrl = normalizeUrl(baseUrl); // 如果 baseUrl 是根路径 "/",则不需要替换 if (normalizedBaseUrl === '/') { return null; } // 创建一个新的内容副本用于修改 let newContent = content; // 替换 baseUrl = "/" 为用户指定的 baseUrl newContent = newContent.replaceAll(`baseUrl = "/"`, `baseUrl = "${normalizedBaseUrl}/"`); // 替换 href="/css 为 href="/baseUrl/css newContent = newContent.replaceAll(`href="/css`, `href="${normalizedBaseUrl}/css`); // 替换 src="/js 为 src="/baseUrl/js newContent = newContent.replaceAll(`src="/js`, `src="${normalizedBaseUrl}/js`); // 如果内容有变化,返回新内容 if (content !== newContent) { return newContent; } return null; } catch (error) { logger.error(`处理文件 ${filePath} 时出错:`, error); return null; } } /** * 确保 URL 前后都有且仅有一个斜杠 */ function normalizeUrl(url: string): string { if (!url) return '/'; // 移除开头的所有斜杠 let normalized = url.replace(/^\/+/, ''); // 移除结尾的所有斜杠 normalized = normalized.replace(/\/+$/, ''); // 如果处理后为空,返回单个斜杠 if (!normalized) return '/'; // 添加开头的斜杠 return '/' + normalized; }
源码地址
完整源码可以在这里找到:path-fixer
解决iOS文档绝对路径问题的CLI工具
https://0bipinnata0.my/posts/cli/replace_absolute_path/