配置

所有 Finch 配置都存储在一个 FinchConfigs 实例中，该实例只创建一次并传递给 FinchApp。本页记录了每个选项及其对应的环境变量。

项目结构

典型的 Finch 项目结构如下：

.
├── lib/
│   ├── app.dart              # FinchApp 设置和 main()
│   ├── configs/
│   │   └── setting.dart      # 应用级常量（可选）
│   ├── controllers/
│   ├── models/
│   ├── db/
│   ├── route/
│   │   ├── web_route.dart
│   │   └── socket_route.dart
│   ├── languages/            # JSON 语言文件 (en.json, fa.json …)
│   └── widgets/              # Jinja 模板文件 (*.j2.html)
├── public/                   # 直接提供服务的静态文件
├── migrations/               # MySQL 迁移 SQL 文件
├── migrations_sqlite/        # SQLite 迁移 SQL 文件
├── .env
└── pubspec.yaml

FinchConfigs

FinchConfigs 是核心配置类。所有构造函数参数都有对应的 .env 回退值。

import 'package:finch/finch_app.dart';
import 'package:finch/finch_tools.dart'; // pathTo(), env

FinchConfigs configs = FinchConfigs(
  // --- 服务器 ---
  port: env.getInt('DOMAIN_PORT', 8080),
  ip: '0.0.0.0',
  domain: env.get('DOMAIN', 'localhost'),
  domainScheme: env.get('DOMAIN_SCHEME', 'http'),

  // --- 路径 ---
  publicDir: pathTo(env.get('PUBLIC_DIR', './public')),
  widgetsPath: pathTo(env.get('WIDGETS_PATH', './lib/widgets')),
  widgetsType: env.get('WIDGETS_TYPE', 'j2.html'),
  languagePath: pathTo(env.get('LANGUAGE_PATH', './lib/languages')),
  pathCache: pathTo(env.get('PATH_CACHE', './cache_routes')),
  pathMigrationMySQL: './migrations',
  pathMigrationSQLite: './migrations_sqlite',

  // --- 语言 ---
  languageSource: LanguageSource.json, // 或 LanguageSource.dart
  // dartLanguages: languageDart,        // languageSource == dart 时使用

  // --- 数据库 ---
  dbConfig: FinchDBConfig(
    enable: true,
    host: env.get('MONGODB_CONNECTION', 'localhost'),
    port: env.get('MONGODB_PORT', '27017'),
    user: env.get('MONGODB_USER', 'root'),
    pass: env.get('MONGODB_PASSWORD', 'password'),
    dbName: env.get('MONGODB_NAME', 'my_app'),
    auth: env.get('MONGODB_AUTH', 'admin'),
  ),
  mysqlConfig: FinchMysqlConfig(
    enable: true,
    host: env.get('MYSQL_HOST', 'localhost'),
    port: env.getInt('MYSQL_PORT', 3306),
    user: env.get('MYSQL_USER', 'db_user'),
    pass: env.get('MYSQL_PASS', 'db_password'),
    databaseName: env.get('MYSQL_DATABASE', 'my_db'),
  ),
  sqliteConfig: FinchSqliteConfig(
    enable: true,
    filePath: env.get('SQLITE_PATH', './app.sqlite'),
  ),

  // --- 邮件 ---
  mailDefault: '[email protected]',
  mailHost: 'smtp.example.com',

  // --- 模板引擎 (Jinja) ---
  blockStart: '{%',
  blockEnd: '%}',
  variableStart: '{{',
  variableEnd: '}}',
  commentStart: '{#',
  commentEnd: '#}',
  // jinjaMapTemplate: mapTemplates, // 提供一个 Map<String,String> 来打包模板

  // --- 安全 ---
  cookiePassword: env.get('COOKIE_PASSWORD', 'change-me-in-production'),

  // --- 开发 ---
  enableLocalDebugger: env.getBool('ENABLE_LOCAL_DEBUGGER', false),
);

关键属性参考

属性	类型	默认值	用途
`port`	`int`	`8080`	HTTP 服务器端口
`ip`	`String`	`'0.0.0.0'`	绑定地址
`domain`	`String`	`'localhost'`	公共域名
`domainScheme`	`String`	`'http'`	`http` 或 `https`
`domainPort`	`int`	同 `port`	生成 URL 中使用的端口
`publicDir`	`String`	`'public'`	静态文件根目录
`widgetsPath`	`String`	`'bin/widgets'`	模板目录
`widgetsType`	`String`	`'html'`	模板文件扩展名
`languagePath`	`String`	`'languages'`	JSON 语言文件目录
`languageSource`	`LanguageSource`	`.json`	`.json` 或 `.dart`
`languages`	`List<String>`	默认语言映射的键	有效语言代码的白名单；请求的语言若不在此列表中，则回退到默认语言。参见本地化
`pathCache`	`String`	`'./cache'`	路由响应缓存目录
`pathMigrationMySQL`	`String`	`'./migrations'`	MySQL 迁移目录
`pathMigrationSQLite`	`String`	`'./migrations_sqlite'`	SQLite 迁移目录
`cookiePassword`	`String`	`'password'`	加密 Cookie 的密钥
`enableLocalDebugger`	`bool`	`false`	在浏览器中启用调试栏
`fakeDelay`	`int`	`0`	添加人工响应延迟（毫秒）
`poweredBy`	`String`	`'Dart Finch'`	`X-Powered-By` 头部值
`noStop`	`bool`	`true`	未处理错误后保持服务器运行

数据库配置类

FinchDBConfig（MongoDB）

FinchDBConfig(
  enable: true,
  host: 'localhost',
  port: '27017',       // String
  user: 'root',
  pass: 'password',
  dbName: 'my_app',
  auth: 'admin',       // 认证源数据库
  maxConnections: 10,  // mongo_dart 连接池的大小（Db.pool）
)

FinchMysqlConfig

FinchMysqlConfig(
  enable: true,
  host: 'localhost',
  port: 3306,          // int
  user: 'db_user',
  pass: 'db_password',
  databaseName: 'my_db',
  collation: 'utf8mb4_general_ci',
  maxConnections: 10,  // MySQLConnectionPool 的大小
)

FinchSqliteConfig

FinchSqliteConfig(
  enable: true,
  filePath: './app.sqlite',
)

环境变量（.env）

Finch 会自动读取项目根目录中的 .env 文件。所有 FinchConfigs 值都可以通过环境变量覆盖。env 映射（来自 finch_tools.dart）同时提供 .env 和系统环境变量的访问。

DOMAIN_PORT=8080
DOMAIN=example.com
DOMAIN_SCHEME=https

MONGODB_CONNECTION=localhost
MONGODB_PORT=27017
MONGODB_USER=root
MONGODB_PASSWORD=secret
MONGODB_NAME=my_app
MONGODB_AUTH=admin

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=db_user
MYSQL_PASS=db_pass
MYSQL_DATABASE=my_db

SQLITE_PATH=./app.sqlite

ENABLE_LOCAL_DEBUGGER=true

isLocalDebug

FinchApp.config.isLocalDebug 在环境变量 LOCAL_DEBUG 设置为 true 时，或当 Dart 以调试模式运行（Console.isDebug）时返回 true。使用此标志来启用详细输出或本地调试栏。

if (FinchApp.config.isLocalDebug) {
  Console.p('调试模式已激活');
}

本页内容