LikeC4 项目配置文件完全指南：从最小配置到多项目架构

LikeC4 项目配置文件完全指南从最小配置到多项目架构【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4LikeC4 的软件架构图由.c4源文件与一个配置文件共同定义配置文件是项目的入口与总控台——它决定了项目的作用域、名称、样式主题、图片别名、自动视图策略以及自定义生成器等一切行为。本指南以官方配置参考文档configuration.md为核心骨架结合仓库packages/config的源码实现schema.ts、load-config.ts 等与 examples 目录中的真实配置示例帮助你掌握每一种配置项的语义、默认值与边界约束并能立即写出可运行的多项目架构配置。配置文件的作用域与命名约定LikeC4 项目的边界由配置文件的位置决定配置所在目录含所有子目录内的全部.c4文件都属于该配置定义的项目。这个约定直接决定了你在仓库中如何组织架构源文件——把likec4.config.json放在某个目录下就等于声明从这里往下都是我的架构。LikeC4 会按任意顺序识别以下配置文件名称源码实现在 filenames.ts 的ConfigFilenames常量中格式文件名JSON / JSON5.likec4rc、.likec4.config.json、likec4.config.jsonJavaScriptlikec4.config.js、likec4.config.mjs、likec4.config.cjsTypeScriptlikec4.config.ts、likec4.config.mts、likec4.config.cts说明官方参考文档列出了 JSON/JS/TS 三种主格式源码 filenames.ts 还额外支持likec4.config.cjs与likec4.config.cts两个 CommonJS 变体可用于无法使用 ESM 的旧环境。非 JSON 配置文件JS/TS相比 JSON 配置多了两个能力可以编写自定义generators生成器以及在加载时通过 bundle-require 与 esbuild 打包执行因此可以在配置中引用其他模块与变量。JSON 配置 Schema永远带上$schemaJSON 配置文件推荐官方建议始终包含$schema字段它指向 LikeC4 官方 JSON Schema可让 IDE 获得完整的校验与自动补全{ $schema: https://likec4.dev/schemas/config.json, name: my-project }源码层面配置对象由 Zod v4 的LikeC4ProjectJsonConfigSchemaschema.ts严格解析并经过validateProjectConfig校验JSON5 格式的解析由 parseProjectConfigJSON 完成内部使用JSON5.parse因此你的 JSON 文件可以带注释、允许尾逗号。一个常见误区是省略$schema// ❌ 缺少 $schema —— IDE 无法提供校验与自动补全 { name: my-project } // ✅ 正确 —— 带上 schema 获得 IDE 支持 { $schema: https://likec4.dev/schemas/config.json, name: my-project }全部配置项详解name必填项目唯一标识。约束严格源码中通过两个refine校验schema.ts不能为空字符串不能是defaultdefault是保留名不能包含.、、#这三个字符官方提示尽量使用 A-z、0-9、_和-。{ name: cloud-platform }title人类可读的项目标题会展示在生成的站点、IDE 与图表面板中。若填写则不能为空字符串{ name: cloud-platform, title: Cloud Platform Architecture }metadata任意的键值对用于记录自定义项目信息例如归属团队、业务域、版本号。它是z.record(z.string(), z.any())值可以是任意 JSON 类型{ metadata: { owner: platform-team, domain: payments, version: 2.0 } }contactPerson参与创建或维护该项目的人员字符串类型填写时不能为空{ contactPerson: Jane Doe }include引用外部目录中额外的.c4文件用于跨项目共享模型。各子项及其默认值、约束源码在 schema.include.ts{ include: { paths: [../shared, ../common/specs], maxDepth: 5, fileThreshold: 50 } }属性类型默认值约束与说明pathsstring[]必填要扫描的相对目录路径必须是相对路径不允许前导/、盘符或://协议相对于配置文件所在目录maxDepthnumber3目录扫描深度取值 1–20防止对深层目录过度扫描fileThresholdnumber30从 include 路径加载的文件数超过该值时发出警告帮助发现误包含大目录导致的性能问题取值 1–10000提示maxDepth与fileThreshold的边界值1–20、1–10000以及默认值均可在 schema.include.ts 中核实。若include配置整体非法LikeC4ProjectConfigOps.normalizeInclude会回退到{ paths: [], maxDepth: 3, fileThreshold: 30 }。exclude用 picomatch 风格的 glob 模式排除文件。默认值为[**/node_modules/**]{ exclude: [**/node_modules/**, **/generated/**] }inferTechnologyFromIcon当元素没有显式设置technology时是否从图标名自动推导技术栈。作用于aws:、azure:、gcp:、tech:前缀的图标bootstrap 图标除外。默认true{ inferTechnologyFromIcon: false }implicitViews为没有显式视图的元素自动生成作用域视图从而支持下钻导航。默认false{ implicitViews: true }imageAliases为图片目录路径定义快捷别名。默认别名指向./images。源码schema.image-alias.ts规定别名键必须以开头匹配/^[A-Za-z0-9_-]*$/值必须是相对路径不允许前导/、盘符或协议{ imageAliases: { : ./images, shared: ../../shared-images } }manualLayouts配置手动布局数据的存储位置。outDir相对于配置文件所在目录默认.likec4源码见 schema.ts{ manualLayouts: { outDir: .likec4 } }仓库示例 examples/multi-project/projectA/likec4.config.json 演示了将布局输出到.likec4/layouted子目录的用法。styles主题定制与默认样式是配置项中最丰富的一个其完整 Schema 在 schema.theme.ts 中定义。结构分三部分{ styles: { theme: { colors: { primary: #FF6B6B, secondary: rgba(37,99,235,1) } }, defaults: { border: dashed, opacity: 100, size: md, relationship: { color: gray, line: dashed } } } }结合源码补充细节theme.colors可覆盖主题色。颜色值支持任意合法 CSS 颜色格式hex、rgb、rgba、hsl、hsla 等或拆分为更细的取值结构elementsfill填充、stroke描边、hiContrast高对比文字/标题色、loContrast低对比文字/描述色与relationshipsline线条色、label标签文字色、labelBg标签背景色默认rgba(0, 0, 0, 0.5)。ThemeColorValuesSchema的computeColorValues转换逻辑见 schema.theme.ts。theme.sizes覆盖各尺寸sm/md/lg等的width/height尺寸宽高均要求不小于 50。defaults元素的默认样式兜底值——color必须是主题中存在的颜色名、opacity0–100 整数、bordersolid/dashed/dotted等、size、shape、iconPosition以及嵌套的group组的color/opacity/border与relationship关系的color/line/arrow。customCss源码新增能力官方参考文档未列一个 CSS 文件路径或路径数组会被包含进生成的图表中用于深度自定义渲染样式。仓库中 examples/multi-project/dyn-config/likec4.config.mjs 展示了在 TS/JS 配置里组合styles.defaults.opacity: 10的写法。extends从其他配置文件仅 JSON继承样式。值为单个路径或路径数组。注意extends只合并styles其余字段以本配置文件为准{ extends: ../shared/likec4.config.json } { extends: [../shared/base.json, ../shared/theme.json] }加载机制的实现值得关注load-config.ts 会递归解析extends链将链上所有配置的styles用defu合并链末端的配置优先级最高见 load-config.ts并且内置了循环引用检测——若 A extends B 且 B extends A会抛出Config extends cycle detected: A - B - A错误。仓库 examples/multi-metadata-extend 目录演示了通过extends与多份配置叠加元数据的场景。landingPage配置生成站点的着陆页行为三种互斥形式LandingPageSchema见 schema.ts重定向到索引视图{ landingPage: { redirect: true } }只展示指定视图include列表不可为空选择器不能是#{ landingPage: { include: [overview, cloud-detail] } }隐藏指定视图{ landingPage: { exclude: [internal-debug] } }generators仅 TypeScript/JS 配置可用自定义生成器从模型产生任意输出文件。这是非 JSON 配置独有的能力借助 defineConfig 获得完整的类型推导与运行时校验import { defineConfig } from likec4 export default defineConfig({ name: my-project, generators: { my-gen: async ({ likec4model, ctx }) { const elements likec4model.elements() await ctx.write({ path: output.json, content: JSON.stringify(elements, null, 2), }) }, }, })运行生成器likec4 gen my-genVSCode 中对应命令为LikeC4: Run code generator。生成器函数接收{ likec4model, ctx }两个参数类型定义在 schema.tslikec4model是完整的 LikeC4 模型可枚举元素、关系、视图ctx提供write()写出文件路径相对项目目录自动创建目录、locate()定位任意元素/关系/视图在源文件中的精确位置与abort()。仓库 examples/multi-project/dyn-config/likec4-generators.mjs 是一个可直接运行的示例它为每个视图生成一个 JSON 快照文件到源文件同级的views/目录。也可以配合defineGenerators将生成器抽成独立模块复用见 define-config.ts。webapp源码新增能力官方参考文档未列出的补充配置项见 schema.ts用于控制生成 Web 应用的行为exportFormats启用的导出格式数组取自[png, jpg, dot, d2, mmd, puml, drawio]见 webapp-export-formats.ts。省略则启用全部传空数组则禁用 Web 应用导出不允许重复项。relationshipsBrowser.defaultScope关系浏览器的默认作用域取global或view默认view。多项目Multi-Project设置工作区内每个配置文件定义一个独立项目目录层级中距离最近的配置文件决定.c4文件归属哪个项目workspace/ ├─ project-a/ │ ├─ likec4.config.json ← project a │ ├─ model.c4 │ └─ views.c4 ├─ project-b/ │ ├─ likec4.config.json ← project b │ └─ model.c4 └─ shared/ └─ common.c4 ← 通过 include.paths 引入跨项目共享.c4文件的推荐方式就是include.paths。仓库的 examples/multi-project 目录提供了完整的多项目样例其中 projectA/likec4.config.json 与 projectB/architecture.c4 展示了两个独立项目如何并存而dyn-config项目则演示了如何在 TS 配置中组合include、styles与generators。另外需要注意一个加载细节非 JSON 配置文件加载时loadConfig会把配置所在目录名作为隐式name兜底load-config.ts 中的implicitcfg { name: basename(folder) }也就是说即使你忘了写name配置也不会直接失败——但请始终显式声明name避免命名失控。最小起步配置一个可以直接复制使用的起点{ $schema: https://likec4.dev/schemas/config.json, name: my-project, title: My Architecture }重要提醒务必包含$schema——它能为配置文件启用 IDE 自动补全与校验避免手写配置时因拼写错误或取值越界如opacity: 150、name含而踩坑。仓库中几乎每个示例都遵循这一约定例如 examples/metadata-views/likec4.config.json。配置加载与校验机制速览了解配置是如何被读取的有助于排查问题。核心入口是 loadConfigJSON/JSON5 配置读取文件内容后经JSON5.parse解析因此支持注释与尾逗号递归解析extends链含循环检测合并styles最后经validateProjectConfig严格校验。非 JSON 配置通过bundleRequire esbuild 打包执行为提升加载速度load-config.ts 会把likec4/config的导入拦截并替换为轻量 mockdefineConfig等直接透传避免重复打包整个 config 包。任何校验失败都会通过z.prettifyError输出可读的错误信息如Config validation failed: ...并抛出明确异常。这些机制的单元测试覆盖在 schema.spec.ts 与 schema.theme.spec.ts 中读者可以结合测试用例进一步理解各配置项的取值边界。小结配置文件是 LikeC4 项目的心脏用name定义唯一身份用include/exclude划定模型边界用styles/extends统一视觉体系用imageAliases管理图片资源用implicitViews开启自动下钻用landingPage控制站点入口用generators把模型变成可编程的输出管道。结合 configuration.md 参考文档与packages/config源码你现在应该能够为单项目、多项目乃至带自定义生成器的复杂场景写出准确、可维护的 LikeC4 配置。【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考