JoinQuant 定时任务避坑：run_weekly 的 force 参数详解与机制分析

请根据以下 SEO 主题生成完整页面内容：

Title: joinquant 定时任务避坑：run_weekly 的 force 参数作用机制

Question: run_weekly 中的 force=True 和 force=False 对首周交易日执行有什么影响？

在 JoinQuant（聚宽）量化交易平台中，run_weekly 用于指定每周特定交易日和时间点运行自定义函数。force 参数主要影响策略刚启动（注册回调函数）的第一周的执行逻辑。以下是 force=True 与 force=False 的核心区别与作用机制：

---

1. 核心概念与作用机制

force 参数的作用定义为：若注册回调函数的时间晚于第一次回调的执行时间，是否就近补充执行。

• force=True（默认值/建议慎用）：
  若策略开始运行的时刻（或注册定时任务时）已经错过了本周指定的交易日或时间，系统会就近补执行一次回调函数，确保策略不会漏掉当周的任务。

• force=False（建议显式设置）：
  若注册时间晚于本周应执行的时间点，系统不会就近补执行，而是跳过错过的执行点，严格等待下一个周期的指定时间再触发。

---

2. 首周执行影响示例对比

假设策略配置如下：

def initialize(context):
    # 设定每周第 1 个交易日（通常为周一）开盘 09:30 运行 weekly_func
    run_weekly(weekly_func, weekday=1, time='09:30', force=True)

如果策略在 周三（例如 3 月 20 日） 开始启动运行：

情况 A：force=True

• 机制：系统识别到周一（第 1 个交易日）的 09:30 已经过去，但因为 force=True，系统会认为策略刚启动需要补做逻辑，因此会在启动当天（周三）就近触发一次 weekly_func。
• 影响：可能导致策略在周三运行了本应在周一运行的调仓逻辑，打乱原有的周频调仓节奏。

情况 B：force=False

• 机制：系统识别到本周第 1 个交易日的时间已过，因 force=False，放弃补执行。
• 影响：策略在启动当周（周三、周四、周五）不会触发 weekly_func，而是平静等待下一周的第一个交易日 09:30 才首次触发。

---

3. 避坑指南与最佳实践

1. 首周多调仓风险：
   若策略包含自动建仓或调仓逻辑，使用 force=True 可能会在回测或模拟盘刚启动时产生意料之外的“立即下单”行为。强烈建议在生产环境和回测中显式指定 force=False。

2. 配合 run_monthly 一起使用：
   run_monthly 同样具有 force 参数，机制与 run_weekly 完全一致。在月度调仓策略中，设置 force=False 可避免月中启动策略时误触发月初的调仓逻辑。

3. 推荐写法：

   def initialize(context):
       # 设置开启动态复权
       set_option('use_real_price', True)
       
       # 每周第一个交易日 09:30 运行，建议显式设置 force=False
       run_weekly(my_weekly_trade, weekday=1, time='09:30', force=False)