Docz 自定义配置文件位置(custom-config-location):`--config` 参数与 `src/doczrc.js` 实战指南

原创2026-09-19 15:34:501,961 阅读
文章标签:文档静态站点开发工具

Docz 自定义配置文件位置(custom-config-location):--config 参数与 src/doczrc.js 实战指南

导读

Docz 默认在项目根目录查找 doczrc.js 配置文件,但大型项目或 monorepo 场景下,往往需要把配置放进 src/ 等子目录统一管理。本文以仓库内 examples/custom-config-location 示例为主线,完整讲解如何通过 --config 命令行参数指定任意位置的配置文件,从创建项目、运行、构建到预览的全流程,并结合 docz-core 源码(argv.ts、docz.ts、create-resources.ts)剖析其底层解析与复制机制,让你既能直接上手,也能理解原理。

一、示例项目一览

examples/custom-config-location 是一个极其精简的 Docz 2.x 示例,核心结构如下:

examples/custom-config-location/
├── package.json            # 脚本中通过 --config 指定配置位置
└── src/
    ├── doczrc.js           # 放在 src/ 目录下的 Docz 配置
    ├── index.mdx           # 文档首页
    └── components/
        ├── Alert.jsx
        └── Alert.mdx

它的 package.json 定义了三个与配置位置强相关的脚本:

{
  "scripts": {
    "dev": "docz dev --config src/doczrc.js",
    "build": "docz build --config src/doczrc.js",
    "serve": "docz serve"
  },
  "dependencies": {
    "docz": "latest",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }
}

关键点在于:dev 和 build 都通过 --config src/doczrc.js 告诉 Docz 去 src/ 目录读取配置,而不是默认的根目录 doczrc.js。

而 src/doczrc.js 的内容本身非常简单:

export default {
  menu: ['Getting Started', 'ComponentsA', 'ABD'],
  title: 'My Documentation Title',
}

这里 menu 用于自定义侧边栏菜单顺序,title 用于覆盖文档站点标题(默认取自 package.json 的 name 字段)。配置放在 src/ 下,意味着所有与站点相关的资源(组件、文档、配置)可以收敛在同一个目录,便于团队协作与目录整洁。

二、快速创建:使用 create-docz-app

方式一:npx

npx create-docz-app docz-app --example custom-config-location

方式二:yarn

yarn create docz-app docz-app --example custom-config-location

create-docz-app 会以本示例为模板,在 docz-app 目录下生成一个完整可运行的项目,其中 src/doczrc.js 与上述脚本已预置好,直接进入“运行”环节即可。

三、手动下载示例

如果不使用脚手架,也可以直接从本仓库手动抽取该示例(以 Linux/macOS 下的 curl 为例):

curl https://codeload.github.com/doczjs/docz/tar.gz/main | tar -xz --strip=2 docz-main/examples/custom-config-location
mv custom-config-location docz-custom-config-location-example
cd docz-custom-config-location-example

解压后得到的就是第二节展示的目录结构。

四、安装依赖

进入项目目录后,二选一安装依赖:

yarn
# 或
npm i

依赖极轻:仅 docz、react、react-dom 与 prop-types,无需额外配置即可启动。

五、开发模式:docz dev --config src/doczrc.js

yarn docz dev --config src/doczrc.js
# 或等价地
yarn dev

5.1 发生了什么:配置的“复制 + 解析”两步走

从源码看,dev 命令(dev.ts)的执行路径是:

export const dev = async (args: Arguments<any>) => {
  copyDoczRc(args.config)
  const config = await parseConfig(args)
  const bundler = gatsby(config)
  const app = await bundler.createApp()
  await app.start()
}

第一步 copyDoczRc(args.config) 是关键。在 create-resources.ts 中:

export const copyDoczRc = (configPath?: string) => {
  const sourceDoczRc = configPath
    ? path.join(paths.root, configPath)
    : path.join(paths.root, 'doczrc.js')
  const hasDoczRc = fs.existsSync(sourceDoczRc)
  if (!hasDoczRc) return
  const destinationDoczRc = path.join(paths.docz, 'doczrc.js')
  fs.copySync(sourceDoczRc, destinationDoczRc)
}

即:传入 --config src/doczrc.js 时,Docz 会把 <项目根>/src/doczrc.js 复制到内部工作目录 .docz/doczrc.js;未传入时则默认取 <项目根>/doczrc.js。.docz 是 Docz 生成的内部 Gatsby 工程目录(见 paths.ts),所有后续模板生成、构建都围绕它展开。

第二步 parseConfig 完成真正的配置解析(docz.ts):

export const parseConfig = async (argv, custom?) => {
  const port = await detectPort(argv.port)
  const defaultConfig = getBaseConfig(argv, { port, ...custom })

  const config = argv.config
    ? loadFrom<Config>(path.join(paths.docz, 'doczrc.js'), defaultConfig)
    : load<Config>('docz', defaultConfig)

  const reduceAsync = Plugin.reduceFromPluginsAsync<Config>(config.plugins)
  return reduceAsync('setConfig', config)
}
  • 传入 --config:直接加载 .docz/doczrc.js(即刚复制过去的文件);
  • 未传入:走 load('docz', ...),即按约定文件名在项目目录中向上查找。

配置加载完成后还会经过 plugins 的 setConfig 钩子链,允许插件对配置做二次加工。

5.2 没有 --config 时会找哪些文件

--config 缺省时,Docz 依赖 load-cfg 的查找列表,按序在当前目录及上层目录(findup)中寻找:

export const finds = (name: string): string[] => [
  `${name}.json`,
  `.${name}rc`,
  `${name}rc.js`,
  `${name}rc.json`,
  `${name}.config.js`,
  `${name}.config.json`,
]

对应到 Docz 即:docz.json、.doczrc、doczrc.js、doczrc.json、docz.config.js、docz.config.json。这也解释了为什么默认约定是根目录的 doczrc.js——它是查找列表中的第一顺位 JS 文件(docz.json 优先但属于 JSON 形式)。

加载机制上,JS 文件通过 @babel/register 转译后 require,兼容 ES Module 的 export default(loadFile 中 file = required.default || required);JSON 文件则直接 readJsonSync。最终配置与默认配置做浅合并:{ ...defaultConfig, ...file }。

5.3 等价的环境变量方式

--config 参数也可以换成环境变量 DOCZ_CONFIG(底层通过 env-dot-prop 读取 docz.config,见 argv.ts):

DOCZ_CONFIG=src/doczrc.js yarn dev

三种方式优先级一致:显式 CLI 参数(或对应环境变量)> 配置文件内容 > 内置默认值。

六、生产构建:docz build --config src/doczrc.js

yarn docz build --config src/doczrc.js
# 或
yarn build

build 命令(build.ts)同样先执行 copyDoczRc(args.config),保证配置被复制到 .docz 下,再 parseConfig、初始化并调用底层 Gatsby bundler 产出静态站点。

构建产物默认输出到 dest 指定的目录,其默认值为 .docz/dist(argv.ts 中 option('dest', { alias: 'd', default: getEnv('docz.dest', '.docz/dist') }))。构建完成后的静态文件即为可部署的文档站点。

七、预览构建产物:docz serve

yarn serve
# 或
npm run serve

注意 serve 脚本没有 --config 参数。这并非遗漏,而是因为 serve 只需要在 .docz 工程内启动 Gatsby 的 serve,配置已在 dev/build 阶段被复制并固化到 .docz/doczrc.js,无需再次指定来源。

serve.ts 的实现会读取已解析配置中的 port 与 host 并透传给 Gatsby serve:

const config = await parseConfig(args)
const cliArgs = ['run', 'serve']
if (config.port) { cliArgs.push('--', '--port', String(config.port)) }
if (config.host) { cliArgs.push('--host', String(config.host)) }
spawnSync('npm', cliArgs)

八、--config 相关的内置参数速查

除 config 外,Docz 还提供一批可通过 CLI/环境变量覆盖的常用参数(定义于 argv.ts),它们在自定义配置场景中经常配合使用:

参数 环境变量 默认值 说明
--config DOCZ_CONFIG ''(空) 配置文件路径,空则按约定文件名查找
--src DOCZ_SOURCE ./ 文档源目录,mdx 等文档所在位置
--files DOCZ_FILES **/*.{md,markdown,mdx} 匹配文档文件的 glob
--ignore DOCZ_IGNORE [] 忽略的文件规则(内置忽略 readme.md 等)
--port, -p DOCZ_PORT 3000 开发服务器端口(自动检测冲突)
--host DOCZ_HOST localhost 开发服务器主机名
--dest, -d DOCZ_DEST .docz/dist 构建输出目录
--title DOCZ_TITLE package.json 的 name 站点标题
--typescript, --ts DOCZ_TYPESCRIPT false 启用 TypeScript 支持
--debug DOCZ_DEBUG false 调试模式
--base DOCZ_BASE / 站点部署的基础路径
--open, -o DOCZ_OPEN_BROWSER null dev 模式下自动打开浏览器

内置默认配置 doczRcBaseConfig(docz.ts)还包括:src: './'、themesDir: 'src'、mdxExtensions: ['.md', '.mdx']、menu: []、plugins: []、mdPlugins: []、hastPlugins: [],以及 ignore 默认规则(readme.md、changelog.md、code_of_conduct.md、contributing.md、license.md)。

九、适用场景与注意事项

  • 目录整洁:将 doczrc.js 与组件、文档一起放入 src/,站点相关资源单目录收敛,适合团队规范统一的项目。
  • 多份配置切换:--config 支持相对路径,可在不同环境(如 CI 与本地)通过不同配置入口启动同一份代码。
  • 配置写法:doczrc.js 支持 export default(ES Module)与 module.exports(CommonJS),JSON 形式(doczrc.json)同样可用。
  • 路径基准:配置中若出现相对路径(如 themesDir),解析基准是项目根目录(paths.ts 通过 getRootDir 归一化),而非配置文件自身所在目录,编写时需留意。
  • 浅合并语义:自定义配置与默认配置是浅合并,数组类字段(如 menu、plugins、ignore)会整体替换默认值,而非追加。
  • 必须存在:若 --config 指定的文件不存在,copyDoczRc 会静默跳过(if (!hasDoczRc) return),随后 loadFrom 加载到空对象,站点将以默认配置运行,可能与你预期的效果不一致,建议先确认路径拼写。

十、小结

通过 --config src/doczrc.js(或 DOCZ_CONFIG 环境变量),Docz 可以在任意位置托管配置文件,其底层机制清晰可靠:启动时 copyDoczRc 将指定配置复制进 .docz/doczrc.js,随后 parseConfig 加载并与内置默认配置浅合并,最终交由 Gatsby bundler 完成 dev、build 与 serve。示例仓库 examples/custom-config-location 提供了可直接运行的完整参考实现,结合 argv.ts、docz.ts 与 load-cfg 源码,即可完全掌握 Docz 配置文件解析的来龙去脉。

登录后查看全文
docz