Configuration Priority Hierarchy in CFnew When Using KV: Complete Guide

CFnew resolves configuration values using a strict four-level hierarchy where URL path parameters take precedence over Cloudflare KV store values, which in turn override Worker environment variables, with built-in defaults serving as the final fallback.

The byJoey/cfnew repository implements a Cloudflare Worker service for subscription management that supports multiple configuration sources. When Cloudflare KV is enabled, understanding the precise resolution order prevents conflicting settings and ensures your deployment behaves predictably.

How CFnew Resolves Configuration Values

According to the project documentation in README.md at lines 59 and 78, CFnew employs a cascading lookup mechanism. The system evaluates potential configuration sources sequentially, stopping at the first level where a valid value is found. This design allows for both programmatic overrides via URL parameters and persistent global settings via the KV store, while maintaining environment-specific fallbacks.

The hierarchy can be summarized as:

path-params > KV-values > env-vars > defaults

The Four-Level Configuration Priority Hierarchy

Level 1: Path and Query Parameters

URL path and query parameters hold the highest precedence in the resolution chain. Any ?key=value pairs appended to the request URL immediately override all other configuration sources.

For example, if a user requests https://worker.workers.dev/abcd?p=1.2.3.4, the p (proxy IP) parameter from the URL wins even if KV contains a different value. This is documented in the README's "客户端 path 参数" section.

Level 2: Cloudflare KV Store Values

When no overriding path parameters exist, CFnew checks the Cloudflare KV store next. The global configuration saved through the graphical interface (GUI) persists here. As noted in the "图形化配置" description, KV values override environment variables but yield to explicit URL parameters.

The main source file 明文源吗 contains the initKVStore and loadKVConfig functions that implement this lookup layer.

Level 3: Worker Environment Variables

If KV returns empty or lacks a specific key, the system falls back to Worker environment variables. These are defined in the Worker's settings (e.g., variables named C, u, or p). This layer provides deployment-specific defaults that persist across requests without requiring KV writes.

Level 4: Built-in Default Values

Finally, if no value exists in the URL, KV, or environment variables, CFnew applies hard-coded default values defined in the source code. These ensure the service remains functional even without any external configuration.

Implementation in the Source Code

The configuration resolution logic resides in 明文源吗 (the main source file). This file implements loadKVConfig to retrieve settings from Cloudflare KV, and initKVStore to initialize the storage interface.

The snippets directory contains the GUI assets that write configuration values to KV, demonstrating how values entered through the web interface are subsequently read by the resolution hierarchy.

Practical Configuration Scenarios

Consider how the hierarchy applies in these three common situations:

// Scenario 1: Path parameter takes absolute precedence
// Request: https://example.workers.dev/abcd?p=1.2.3.4
// KV stores {"p": "5.6.7.8"}, Env has p=2.2.2.2
// Result: Uses 1.2.3.4 from the URL

// Scenario 2: KV overrides environment variables
// Request: https://example.workers.dev/abcd (no query params)
// KV stores {"p": "9.9.9.9"}, Env has p=2.2.2.2
// Result: Uses 9.9.9.9 from KV

// Scenario 3: Fallback to defaults when sources are empty
// Request: https://example.workers.dev/abcd (no query params)
// KV has no "p" entry, Env has no "p" variable
// Result: Uses the built-in default proxyip value

Why This Hierarchy Matters

This structure provides maximum flexibility for administrators. Global defaults can be set via KV through the GUI (snippets), overridden per-deployment via environment variables, and temporarily bypassed via URL parameters for testing or specific client requirements. The strict ordering prevents accidental configuration leaks while allowing targeted overrides.

Summary

• Path parameters always win when present in the request URL
• KV store values serve as the global configuration and override environment variables
• Environment variables provide deployment-specific fallbacks when KV is empty
• Built-in defaults ensure operational continuity when no other sources define a value
• The implementation relies on initKVStore and loadKVConfig in 明文源吗

Frequently Asked Questions

What happens if the same key exists in both the URL and KV store?

The URL parameter takes precedence. According to the README documentation at line 78, path parameters sit at the top of the hierarchy, meaning a value like ?p=1.2.3.4 will override any p value stored in KV or defined in environment variables.

Does CFnew check KV before or after environment variables?

CFnew checks the KV store before falling back to environment variables. When the Worker initializes, it attempts to load configuration via loadKVConfig; only if this returns empty or undefined for a specific key does the system check the Worker's environment variables.

Which file contains the logic for the configuration priority?

The resolution logic is implemented in 明文源吗, which contains the initKVStore initialization function and loadKVConfig retrieval method. The GUI components in the snippets directory handle writing to KV, but the priority enforcement happens in the main Worker script.

Can I run CFnew without using Cloudflare KV at all?

Yes. If KV is not configured or available, the system gracefully falls back to environment variables and then built-in defaults. The initKVStore function handles the KV initialization, but the resolution chain continues through environment variables and defaults if KV is absent, ensuring the Worker remains functional.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}